home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / batutil1.zip / BATUTIL.DOC next >
Text File  |  1990-03-25  |  265KB  |  6,031 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.            BBBBBB    AAA    TTTTTT  UU  UU  TTTTTT   IIII  LLLL    (tm)
  7.             BB BBB  AA AA   T TT T  UU  UU  T TT T    II    LL
  8.             BB  BB AA   AA    TT    UU  UU    TT      II    LL
  9.             BBBBB  AA   AA    TT    UU  UU    TT      II    LL
  10.             BB  BB AAAAAAA    TT    UU  UU    TT      II    LL
  11.             BB BBB AA   AA    TT    UU  UU    TT      II    LL  LL
  12.            BBBBBB  AA   AA   TTTT    UUUU    TTTT    IIII  LLLLLLL
  13.  
  14.  
  15.  
  16.  
  17.  
  18.                                   Version 1.0
  19.  
  20.                                CTRLALT Associates
  21.  
  22.                               _______
  23.                          ____|__     |               (tm)
  24.                       --|       |    |-------------------
  25.                         |   ____|__  |  Association of
  26.                         |  |       |_|  Shareware
  27.                         |__|   o   |    Professionals
  28.                       -----|   |   |---------------------
  29.                            |___|___|    MEMBER
  30.  
  31.  
  32.  
  33.  
  34.       TABLE OF CONTENTS
  35.  
  36.  
  37.       Chapter I:OVERVIEW........................................3
  38.          I.1 Shareware Considerations...........................3
  39.          I.2 What BATUTIL does..................................6
  40.          I.3 Help and Verbose Mode..............................8
  41.          I.4 Basic Syntax......................................10
  42.          I.5 Setting BATUTIL options from the environment......12
  43.          I.6 Reading commands from a file......................13
  44.          I.7 BATUTIL's line editor.............................14
  45.          I.8 The HAltif command................................15
  46.          I.9 Control Break handling............................16
  47.       Chapter II:SYSTEM INFORMATION............................18
  48.          II.1 Overview.........................................18
  49.          II.2 Time.............................................19
  50.          II.3 Operating System and Memory Information..........19
  51.          II.4 Console Information..............................22
  52.          II.5 Hardware Information.............................23
  53.          II.6 File information.................................24
  54.          II.7 The RUn Command..................................27
  55.          II.8 TOdayfile and MAkefile...........................28
  56.          II.9 The ERrorlevel command...........................29
  57.       Chapter III: DISPLAY TOOLS...............................30
  58.          III.1 Overview........................................30
  59.          III.2 Metastring Translation..........................30
  60.          III.3 BATUTIL's ECho command..........................34
  61.          III.4 The PRetty command..............................35
  62.          III.5 Bigecho.........................................36
  63.          III.6 Getting Echo/Pretty Input from a file...........39
  64.          III.7 Cursor Position and Hiding the Cursor...........40
  65.          III.8 The STdout command..............................40
  66.          III.9 Sounds..........................................41
  67.       Chapter IV:USER INPUT....................................43
  68.          IV.1 Menu Basics......................................43
  69.          IV.2 Getting a menu from a file.......................44
  70.          IV.3 Menu Options.....................................45
  71.          IV.4 GEtkey Basics....................................47
  72.          IV.5 GEtkey Options...................................49
  73.          IV.6 AScii, SCanread..................................52
  74.          IV.7 USername.........................................52
  75.          IV.8 Parameter Matching...............................53
  76.          IV.9 Querying the Lock status.........................54
  77.       Chapter V:ENVIRONMENTAL CONTROL..........................55
  78.          V.1 Environmental Impact Statement....................55
  79.          V.2 Environment Reports...............................57
  80.          V.3 SEt basics........................................58
  81.          V.4 Getting User Strings into the Environment.........59
  82.          V.5 Using the file pick list..........................61
  83.          V.6 Saving and loading the environment to a file......62
  84.          V.7 Batch file path control...........................64
  85.          V.8 Direct Editing of the path........................65
  86.          V.9 Direct editing of the environment.................66
  87.  
  88.  
  89.  
  90.  
  91.       Chapter VI:TIPS AND EXAMPLES.............................67
  92.          VI.1 General tips.....................................67
  93.          VI.2 Returning to your initial directory..............67
  94.          VI.3 Using BATUTIL in your autoexec.bat...............68
  95.          VI.4 A shell for LIST.................................70
  96.          VI.5 A two year olds' delight.........................70
  97.          VI.6 Sample batch files...............................71
  98.       Chapter VII:COMMAND REFERENCE............................74
  99.       Chapter VIII:ERROR MESSAGES.............................104
  100.          VIII.1 Fatal Errors..................................104
  101.          VIII.2 List of Error Codes...........................104
  102.          VIII.3 Explanation of Error Codes....................105
  103.  
  104.  
  105.  
  106.  
  107.                         Chapter I:OVERVIEW
  108.  
  109.  
  110.       I.1 Shareware Considerations
  111.  
  112.             BATUTIL is a program included in the STACKEY package by
  113.       CTRLALT Associates.  Full details as to warranty and license terms
  114.       can be found in the STACKEY documentation.  BATUTIL is shareware.
  115.       You have a 30 day trial period from the time that you first use the
  116.       program to see if it meets your needs.  If you continue to use it
  117.       after that time you are required to pay a license fee not as a
  118.       contribution but because you are getting use from our program.
  119.       Shareware is dedicated to the idea that users are best served by a
  120.       chance to fully try out something as complex and individualistic as
  121.       software before they buy it and that authors are served by an ethic
  122.       that encourages wide copying for trial runs.  But in order for the
  123.       system to work you need to respect the trust that we show in you and
  124.       register if you continue to use our program.  BATUTIL can only be
  125.       registered as part of the STACKEY package.
  126.  
  127.             License fees are as follows:
  128.               License to STACKEY with printed docs                  $39
  129.               Consultants License to STACKEY                       $200
  130.       All licensing will get you the latest version on disk.  The printed
  131.       documentation is essentially identical to the documentation on
  132.       disk.  Details about what a consultant's license entitles you are
  133.       contained in the STACKEY docs.  Basically, you cannot distribute
  134.       BATUTIL as part of a package of goods or services for which you
  135.       charge a fee without one of the following:
  136.             -  a separate license for each person receiving the program
  137.             -  a consultant's license and you meet its requirements
  138.             -  the right to distribute this program as shareware for a fee
  139.             -  an arrangement with Ctrlalt Associates
  140.       Details are in the STACKEY documentation.  These restriction do NOT
  141.       apply to copies you give for no fee to others for shareware
  142.       evaluation.
  143.  
  144.             You may register by phoning or writing
  145.  
  146.             Support Group, Inc
  147.             Lake Technology Park
  148.             PO Box 130
  149.             McHenry, MD 21541
  150.             1(800)872-4768    (1-800-USA-GROUP)
  151.             FAX 1(301)387-7322
  152.  
  153.  
  154.  
  155.  
  156.     Chapter I:OVERVIEW                                          Page 3
  157.  
  158.  
  159.  
  160.  
  161.                   Documentation for BATUTIL, Version 1.0 
  162.  
  163.  
  164.       Mastercard/Visa and purchase orders from approved institutions are
  165.       accepted.   This is not the number for support (see below).
  166.  
  167.             Payment of the license fee gives you the right to use any
  168.       version of BATUTIL with a major version number of 1.  If there is a
  169.       Version 2, an update fee may be required.  In addition to the thirty
  170.       day trial period, you may return the disks (and printed
  171.       documentation) for a full refund if you are not totally satisfied
  172.       for a period of 90 days after initial payment.  You have the choice of
  173.       one of two license terms: "use like a book" OR a single user license.
  174.       The former allows you to place copies of this software on as many
  175.       machines as you wish so long as there is NO CHANCE that more than one
  176.       copy of BATUTIL will be loaded into any of the machine's memories at
  177.       one time.  The latter allows you to place copies on all machines for
  178.       which YOU are the principal user even if there is a chance that
  179.       OCCASIONALLY more than one copy is in use (for example, if you use
  180.       BATUTIL on a office machine while a family member might OCCASIONALLY
  181.       use a copy on a home machine at the same time).
  182.  
  183.             The 800 number is for orders only.  Registered users may
  184.       obtain support by writing to CTRLALT Associates or via Compuserve.
  185.       Details can be found in the STACKEY documentation.   In particular,
  186.       Ctrlalt Associates have a section (Section 12) on Compuserve's
  187.       PCVENA forum - leave messages there for 76004,1664.
  188.  
  189.             If you like the program, please give it to your friends,
  190.       place it on bulletin boards and otherwise spread it around.  We
  191.       explicitly allow TRIAL use of it privately and in a commercial
  192.       environment.  You may give it away, but you may not charge for it
  193.       or include it with commercial software without our written
  194.       permission, or include as part of a package of services for which
  195.       you charge without a consultant's license.  An exception is made
  196.       for user groups and shareware software distributors who are
  197.       approved shareware distributors of the Association of Shareware
  198.       Professionals, an organization to which both authors of BATUTIL
  199.       belong.  Details on these restrictions, ASP and information on the
  200.       ASP Ombudsman can be found in the STACKEY documentation.
  201.  
  202.             The following names may be trademarked: Turbo Pascal, Turbo
  203.       Professional, Turbo Plus, Pianoman, Desqview, Omniview, Software
  204.       Carousel, Techhelp, Flambeaux Software, Intel, Microsoft, Lotus,
  205.       123, List, Ultravision, 4DOS, Qemm, 386Max, Eemram.  BATUTIL,
  206.       CTRLALT and STACKEY are trademarks of Ctrlalt Associates.
  207.  
  208.  
  209.  
  210.     Chapter I:OVERVIEW                                          Page 4
  211.  
  212.  
  213.  
  214.  
  215.                   Documentation for BATUTIL, Version 1.0 
  216.  
  217.  
  218.             BATUTIL was written in Turbo Pascal.  Extensive use was made of
  219.       the routines in Turbo Professional published by Turbo Power Software
  220.       and of Turbo Plus published by Nostradamus.  The tunes used in the
  221.       sound command were developed with Pianoman, a shareware program also
  222.       available from Support Group, Inc.
  223.  
  224.             We would like to thank Quarterdeck Office Systems and Sunny
  225.       Hill Software for providing information on the programming
  226.       interfaces to Desqview and Omniview respectively, and Scott
  227.       Bussinger and Kim Kokkonen for comments on our Ctrl-Break handler.
  228.  
  229.             BATUTIL is warranted for no particular purpose.  While we
  230.       have tried to make the program bug free, no software can be
  231.       guaranteed to be free of bugs.  Due to the complex nature of
  232.       computer software CTRLALT ASSOCIATES does not warrant that the
  233.       licensed Software is completely error-free, will operate without
  234.       interruption, or is compatible with all equipment and software
  235.       configurations.  Repair, replacement or refund, at the option of
  236.       the CTRLALT ASSOCIATES, is the exclusive remedy of the customer, in
  237.       the event of a defect.  By using this program, you accept it AS IS
  238.       and agree that we will NOT be held responsible for any damages
  239.       including but not limited to consequential damages or loss of data.
  240.       This includes damages caused by problems of which CTRLALT
  241.       Associates is already aware.  We will attempt to correct any bug
  242.       which is pointed out to us.  Registered users are entitled to use
  243.       bug fixes while still numbered 1.xx.  We do not intend to support
  244.       Version 1.xx once a Version 2.xx is available and you may need to
  245.       pay an upgrade fee to a new version if there are any bug fixes made
  246.       once Version 2.xx is available.  You may ask for a full refund of
  247.       your registration for a period up to 90 days after you register but
  248.       only if you return the program package sent registered users and
  249.       agree to destroy any copies of BATUTIL and STACKEY in your
  250.       possession and cease using the programs.  While we have attempted
  251.       to make this documentation as clear as possible, we cannot
  252.       guarantee that there will not be misunderstanding or user error.
  253.  
  254.             We specifically exclude any warranties, EXPRESS OR IMPLIED,
  255.       including the IMPLIED WARRANTIES OF MERCHANTABILITY or FITNESS FOR
  256.       A PARTICULAR PURPOSE.   SOME STATES DO NOT ALLOW THE IMPLIED
  257.       WARRANTIES TO BE EXCLUDED.  CONSULT A LAWYER TO SEE WHETHER OR NOT
  258.       THE ABOVE EXCLUSIONS APPLY TO YOU IN YOUR STATE.
  259.  
  260.  
  261.  
  262.  
  263.  
  264.     Chapter I:OVERVIEW                                          Page 5
  265.  
  266.  
  267.  
  268.  
  269.                   Documentation for BATUTIL, Version 1.0 
  270.  
  271.  
  272.       I.2 What BATUTIL does
  273.  
  274.             BATUTIL is a program with two purposes: to give you power
  275.       inside your batch files and to give you more control over the DOS
  276.       environment.  Included in the information that you can get returned
  277.       in either the DOS errorlevel or an environmental variable are
  278.             -  current time, date, day of the week
  279.             -  total amount and amount free of disk space, memory and EMS
  280.             -  CPU type and type of coprocessor if present
  281.             -  whether a file exists not only in the current directory
  282.       but on the DOS path and if it exists on the DOS path, the actual
  283.       directory can be returned in another environmental variable
  284.             -  whether a file has today's date or not
  285.             -  whether one of two files is older than another
  286.             -  you can parse a filespec into individual components
  287.       Some of these options may not seem so useful at first sight, but,
  288.       for example, whether a file has today's date or not can be used to
  289.       make a routine that will only get run once per day.  Chapter VI
  290.       will explain sample uses of BATUTIL.
  291.             -  whether Desqview, Carousel or Omniview is running and, if,
  292.       so which partition you are in
  293.  
  294.             Central to the design of BATUTIL is the notion of "high level"
  295.       language.  There are much more sophisticated batch languages
  296.       available and in them one can write menus at least as involved as
  297.       are available in BATUTIL's MENU command.  But doing so requires you
  298.       to write a little program in the batch language while MENU is a
  299.       built in command of BATUTIL.  Virtually all the language elements
  300.       (branching) will come from DOS' IF command (although BATUTIL does
  301.       have a HAltif command, which is primitive but useful).
  302.  
  303.             In addition to getting information from the operating system,
  304.       you can pass information to and get information from the user.
  305.       BATUTIL gives you considerable control over displaying information
  306.       including the possibility of turning the cursor on and off and
  307.       displaying messages in various colors.   And BATUTIL understands
  308.       the metastrings that STACKEY does so you can easily display data
  309.       like today's date in English.
  310.  
  311.             As for user input it can be obtained in various forms
  312.             -  There is a getkey routine that lets you list a set of keys
  313.       using STACKEY syntax and get which key in the list the user has hit
  314.             -  whether a lock key is currently pressed
  315.             -  with some simple commands, you can popup an elegant menu
  316.  
  317.  
  318.     Chapter I:OVERVIEW                                          Page 6
  319.  
  320.  
  321.  
  322.  
  323.                   Documentation for BATUTIL, Version 1.0 
  324.  
  325.  
  326.       for the user to pick from and have the choice returned in the
  327.       errorlevel
  328.             -  You can have the user input a string and get it stored in
  329.       the environment
  330.             -  You can have the user type in a user name or password and
  331.       see whether it matches a predetermined list and have which item is
  332.       matched reported in the errorlevel
  333.             -  You can popup a filename list for the user to choose from
  334.       and have the answer stored in the environment
  335.  
  336.             BATUTIL also gives you considerable control over the DOS
  337.       environment.  It is able to do this by using undocumented features
  338.       of the operating system.  As always, such features should be used
  339.       with care.  PLEASE READ CAREFULLY THE WARNING AT THE START OF
  340.       CHAPTER V CONCERNING USING UNDOCUMENTED FEATURES TO ACCESS THE DOS
  341.       ENVIRONMENT.  BATUTIL's environmental control has been tested with
  342.       PCDOS Version 2.0, 2.1, 3.0, 3.1, 3.2, 3.3, 4.0 and some flavors of
  343.       MSDOS.  Besides being able to place information into the
  344.       environment via user input, BATUTIL will
  345.             - display more information about the environment than the SET
  346.       command
  347.             - allow you to put strings in the environment up to a length
  348.       of 255 characters rather than the 127 character maximum that DOS
  349.       allows.  In particular, with BATUTIL, your PATH string can be up to
  350.       250 characters rather than the 122 characters that you can enter
  351.       with DOS.  While DOS doesn't care about long paths, you may have an
  352.       application program that does and crashes if it finds a path over
  353.       127 bytes (during the entire testing period, we only found one
  354.       program Techhelp from Flambeaux Software with this problem).
  355.             - allow simple commands to add a directory to your PATH
  356.       without inadvertently adding one already there and allow deletion
  357.       of a directory from your PATH
  358.             - allow full screen editing of your environment and PATH.
  359.             - allow you to save the environment to a file, to load or
  360.       merge a file into the environment and to kill the environment (use
  361.       with care).
  362.  
  363.             The files in the BATUTIL package are as follows:
  364.                 BATUTIL.EXE     The basic program.  The only file
  365.                                   required to use BATUTIL
  366.                 BATUTIL.HLP     Online help called by BATUTIL if you
  367.                                   use BATUTIL ? or BATUTIL !
  368.                 BATUTIL.DOC     Documentation in electronic form
  369.                 BUDEMO.BAT      Sample batch file which will call
  370.  
  371.  
  372.     Chapter I:OVERVIEW                                          Page 7
  373.  
  374.  
  375.  
  376.  
  377.                   Documentation for BATUTIL, Version 1.0 
  378.  
  379.  
  380.                                   the other sample batch files
  381.                 COLORDEM.BAT    Sample batch file shows color capability
  382.                 EQUIP.BAT       Sample batch file shows ability to read
  383.                                   hardware
  384.                 INPUTDEM.BAT    Sample batch file shows ability to get
  385.                                   input from the user
  386.                 MENUDEMO.BAT    Sample batch file shows BATUTIL's menu
  387.                                   making capability
  388.                 SHOWDEMO.BAT    Sample batch file shows display options
  389.                                   including big characters and metastrings
  390.                 SOUNDEMO.BAT    Sample batch file with BATUTIL's 20
  391.                                   sounds/tunes
  392.                 WHATEL.EXE      Program described in Section II.7 to
  393.                                   determine errorlevel and timing for
  394.                                   some command
  395.  
  396.             BATUTIL, its help file and documentation are copyright 1988-
  397.       90 by Barry Simon and Richard Wilson, all rights reserved.
  398.  
  399.             If you obtain BATUTIL/STACKEY from Support Group, Inc
  400.       directions for installing the programs can be found in the STACKEY
  401.       docs and with a readme.com file.
  402.  
  403.       *******************************************************************
  404.                                 IMPORTANT NOTES
  405.             Users of 4DOS version 2.x; please read Section V.1 before
  406.       calling for technical support.
  407.             CTRLALT Associates wishes to warn you that the SO command may
  408.       change in future versions - the precise sounds for sounds 1-10 may
  409.       change.
  410.             In addition, future versions of BATUTIL may adopt the Windows
  411.       standard use of & in menu choices so you should avoid the use of
  412.       the & symbol in your menu choices (although && for & will be
  413.       supported).
  414.       *******************************************************************
  415.  
  416.  
  417.       I.3 Help and Verbose Mode
  418.  
  419.             You can obtain interactive help for BATUTIL by typing in
  420.               BATUTIL ?
  421.       or
  422.               BATUTIL !
  423.       at the DOS prompt.  To obtain help, the binary file BATUTIL.HLP
  424.  
  425.  
  426.     Chapter I:OVERVIEW                                          Page 8
  427.  
  428.  
  429.  
  430.  
  431.                   Documentation for BATUTIL, Version 1.0 
  432.  
  433.  
  434.       must be available in the current directory or the directory where
  435.       BATUTIL is loaded or in your path.  BATUTIL looks for the first two
  436.       non-blank characters following the ? (or !) and if they are a valid
  437.       BATUTIL command, you will be immediately sent to the help for that
  438.       command; otherwise, the main help menu will be displayed.  For
  439.       example
  440.             BATUTIL ? SE
  441.       would display help for BATUTIL's SET command as would
  442.             BATUTIL ?see the beautiful program
  443.  
  444.             BATUTIL ? displays the menu oriented help with various
  445.       special effects.  If these effects and the slightly longer time
  446.       they take bother you, BATUTIL ! will display help without the
  447.       special fades for displaying material.
  448.  
  449.             The help program uses color attributes on a graphics monitor.
  450.       If you have a two color graphics monitor (such as on a laptop) or
  451.       the colors are hard to see, the help program will use monochrome
  452.       attributes if you use
  453.             SET BU!=bw
  454.       in your autoexec.bat file or at the DOS command line before running
  455.       BATUTIL. Note that on a true monochrome adapter (IBM MDA or
  456.       Hercules monographics card), the help program will not use color
  457.       attributes whether you use that set command or not.
  458.  
  459.             Normally, BATUTIL exits when there is an error and sets the
  460.       errorlevel between 200 and 253; see the discussion in Chapter VIII.
  461.       There are three levels of visual error reporting that you can have
  462.       turned on.  For debugging purposes the default is a verbose mode
  463.       where BATUTIL will explain why it is exiting.  For batch files you
  464.       distribute you may want to have verbose mode turned off and instead
  465.       use a Quiet mode where no messages are displayed.  To turn on this
  466.       quiet mode, just make the first non blank character in the command
  467.       line the letter Q.  Thus,
  468.             BATUTIL {}
  469.       would display an error message while
  470.             BATUTIL Q {}
  471.       would exit without any message.  For distributed batch files made
  472.       with BATUTIL, you may want to turn on quiet mode using an
  473.       environmental variable as described in Section I.5. Command line
  474.       mode takes precedence over any mode set in the environment and, in
  475.       particular, you can override the mode set in the environment and
  476.       restore to the default Verbose mode by making V the first letter on
  477.       the command line after "BATUTIL".
  478.  
  479.  
  480.     Chapter I:OVERVIEW                                          Page 9
  481.  
  482.  
  483.  
  484.  
  485.                   Documentation for BATUTIL, Version 1.0 
  486.  
  487.  
  488.             Chapter VIII has a complete list of error codes with an
  489.       explanation of each.  The online help main menu has an option to
  490.       list all error numbers and their meaning.
  491.  
  492.             In batch files, the error message may disappear too fast for
  493.       you to see.  In addition to Verbose mode, BATUTIL has a Pause mode
  494.       which shows the error message and waits for a key before exiting.
  495.       Pause mode is set with the letter P.
  496.  
  497.             To see the information which BATUTIL is placing in the
  498.       environment while testing out what a command will do the following
  499.       one line batch file (or an equivalent CED synonym) is useful:
  500.             batutil %1 %2 %3 %4 %5 %6 %7 %8 %9 {EC $x(rc)}
  501.       The final command echoes the current value of the environmental
  502.       variable RC to the screen.
  503.  
  504.  
  505.       I.4 Basic Syntax
  506.             Command: REmark
  507.  
  508.             You give BATUTIL a series of commands on the command line.
  509.       There are about 100 different commands - lest that overwhelm you, we
  510.       note that many are just giving different pieces of hardware
  511.       information which you'll rarely want and even the most complex idea
  512.       (menus) are controlled by one basic command and fewer than ten
  513.       commands which effect options like whether the menu explodes.
  514.       Chapter VII is a detailed alphabetical command reference.  When you
  515.       invoke BATUTIL's help, one option is an alphabetical list of
  516.       commands which will give you a panel with syntax and parameters for
  517.       each.
  518.  
  519.             The basic syntax is
  520.               BATUTIL {command1} {command2} ...
  521.       Each command is placed inside braces {} (or square brackets []; see
  522.       below).  The braces are critical - it doesn't matter whether you
  523.       have spaces between } and the next { or not.
  524.  
  525.             All commands have a two element minimal truncation.  That is
  526.       all commands are distinguished already in the first two symbols and
  527.       any substring of the command that has at least two letters will
  528.       work.  For example, the basic command to get a report on the
  529.       environment is
  530.             BATUTIL {envrep}
  531.       The minimal truncation for that is EN so we'll often write ENvrep
  532.  
  533.  
  534.     Chapter I:OVERVIEW                                         Page 10
  535.  
  536.  
  537.  
  538.  
  539.                   Documentation for BATUTIL, Version 1.0 
  540.  
  541.  
  542.       to emphasize this.  Thus
  543.             BATUTIL {en}
  544.       or
  545.             BATUTIL {envr}
  546.       would work just as well as the full name.  The basic commands are
  547.       not case sensitive so {EN} or {En} or even {eNvRe} would do the
  548.       same thing as {envrep}.
  549.  
  550.             Roughly fifty of the commands return to the user (i.e. you
  551.       as a batch file writer) a number from 0 to 199.  If the command in
  552.       question appears inside {} then that number is stored in the
  553.       environmental variable RC (short for "return code"; environmental
  554.       variable are discussed at the start of Chapter V).  If the command
  555.       appears in [], then BATUTIL will exit without running the rest of
  556.       the command line and place this integer in the DOS errorlevel where
  557.       you can test it with commands like
  558.             if errorlevel ....
  559.       (see Chapter VI).  IF THE LAST COMMAND ON THE LINE RETURNS AN
  560.       INTEGER AND IT IS PLACED IN {}, THEN the integer is both placed in
  561.       the real environment and placed in the error level.  For example,
  562.       DRive reports the current drive with 0=A, 1=B, etc.  If the current
  563.       drive is D, then
  564.             BATUTIL .... [DR]
  565.       will set the errorlevel to 3, while
  566.             BATUTIL .....{DR} {echo hi there!}
  567.       would set an environmental variable RC to 3 and then echo "hi
  568.       there!".  Thus if you ran the SET command after batutil, you'd find
  569.       the line
  570.             RC=3
  571.       on your screen.
  572.  
  573.             Some commands will take optional parameters which also appear
  574.       inside the braces for that command.  Thus @Disk gives the free disk
  575.       space.  If no parameter is specified, then the current default
  576.       drive will be used.  Otherwise you can specify a drive as in
  577.             BATUTIL {@D C}
  578.       BATUTIL will object to incorrect syntax so if you tried
  579.             BATUTIL {@D 3}
  580.       then BATUTIL will exit (with an appropriate message if Verbose mode
  581.       is on).  You can separate the command from the first parameter by
  582.       any of the following:
  583.             <space>,<comma>,= or :
  584.       Rules of separation of multiple parameters for those few commands
  585.       which accept multiple parameters depend on the commands.
  586.  
  587.  
  588.     Chapter I:OVERVIEW                                         Page 11
  589.  
  590.  
  591.  
  592.  
  593.                   Documentation for BATUTIL, Version 1.0 
  594.  
  595.  
  596.             Before doing anything BATUTIL scans the command line and
  597.       makes sure that every command is a proper one for this version of
  598.       BATUTIL.  If not, it will exit.  Otherwise, it will execute the
  599.       commands one at a time.  It does not check for parameter syntax
  600.       until that command is reached.  Thus {@D 3} will halt BATUTIL when
  601.       reached but earlier commands will already have run.
  602.  
  603.             We are well aware that many of you will run into the problem
  604.       that DOS limits commands to 127 characters.  As we will explain in
  605.       Section I.6, three commands will read parameters in from a file.  We
  606.       hope that a future release will allow reading in a file of all
  607.       commands.  User feedback will determine how high on the list we put
  608.       such an enhancement.
  609.  
  610.             You may place remarks in the BATUTIL command line by
  611.       enclosing them inside {} with the REmark command as in
  612.             BATUTIL {AT 4F}{CL}{REM clears the screen in red!}
  613.  
  614.  
  615.       I.5 Setting BATUTIL options from the environment
  616.  
  617.             When BATUTIL loads, before reading the rest of its command
  618.       line, it looks for an environmental string of the form
  619.             BU@=string
  620.       and it first reads that string as if it were a command line and
  621.       places the commands in it to be processed first.  This is intended
  622.       primarily to allow you to change the built in default options to
  623.       some other value.  For example, to turn off beeps and change the
  624.       default on GEtkey from flushing the keyboard to not, you'd use:
  625.             BU@={NB}{NF}
  626.  
  627.             This option is useful if you want to permanently turn on
  628.       pause mode; you'd use
  629.             BU@=P {NB}
  630.       if you wanted to also turn beeps off.
  631.  
  632.             Since BATUTIL looks in the environment, you place the
  633.       information that you want there using the DOS SET command (or
  634.       BATUTIL's SET command if you want!); for example, you might place a
  635.       line
  636.             set BU@=P {NB}
  637.       in your autoexec.bat file.  It is important to place NO spaces
  638.       between BU@ and the =.  Spaces after the = are unimportant.
  639.  
  640.  
  641.  
  642.     Chapter I:OVERVIEW                                         Page 12
  643.  
  644.  
  645.  
  646.  
  647.                   Documentation for BATUTIL, Version 1.0 
  648.  
  649.  
  650.             There are three other environmental variables of interest.
  651.       One is the variable BU$.   At the end of the commands to edit your
  652.       path and the environment ({PAthedit} and {EDitenv}) and after using
  653.       help, a screen will appear reminding you of the fact that BATUTIL
  654.       is shareware limited to a 30 day trial period.  You can suppress
  655.       this screen by placing
  656.             BU$=I paid
  657.       in your environment.  Obviously, having told you the secret, you
  658.       can do it even if you haven't paid - let your conscience be your
  659.       guide.  The variable BU^ can be used to turn off ^Break handling;
  660.       see Section I.9.
  661.  
  662.             The final environmental string that BATUTIL pays attention to
  663.       is CUR (for CURSOR).  It looks for two possibilities:
  664.             CUR=no
  665.       Normally, BATUTIL restores the cursor when exiting, even if you
  666.       have turned it off with the {CU -} command of Section III.7  If
  667.       this string is present the cursor is not turned back on but its
  668.       state is not changed.  The other possibility is
  669.             CUR=off
  670.       When starting or exiting the program, BATUTIL will turn the cursor
  671.       off if this string is found at that point.  All other values of CUR
  672.       are ignored.
  673.  
  674.             Because it takes a noticable time for BATUTIL to load,
  675.       if you are processing multiple BATUTIL lines in a batch file, you
  676.       may want to have the cursor turned off.
  677.  
  678.  
  679.       I.6 Reading commands from a file
  680.  
  681.             Three commands are able to read information in from a file.
  682.       The ECho command displays text on the screen in colors you set
  683.       before the echo command; PRetty displays text in colors that you can
  684.       adjust as part of the string displayed and MEnu displays a user
  685.       defined menu.  The analogous file reading commands are FEcho,
  686.       FPretty and FMenu.  Each command takes two parameters: the first is
  687.       a filename and is required, the second a label name which is
  688.       optional.  If the filename is given without a drive or directory,
  689.       then it is searched for first in the current directory. If not found by
  690.       BATUTIL, BATUTIL will attempt to add an extension of bat and look
  691.       again.  Then the same search is made in the directory that batutil was
  692.       loaded from (under DOS 3.0 and later) and finally in the DOS path.  If
  693.       still not found, BATUTIL exits and an error message is issued.
  694.  
  695.  
  696.     Chapter I:OVERVIEW                                         Page 13
  697.  
  698.  
  699.  
  700.  
  701.                   Documentation for BATUTIL, Version 1.0 
  702.  
  703.  
  704.             If no label name is given, then BATUTIL will start reading and
  705.       processing the file from its beginning.  If a label is given,
  706.       BATUTIL reads the file from the beginning but searches until it
  707.       find a line beginning with
  708.             :label
  709.       (leading spaces before the : are ignored and labels are NOT case
  710.       sensitive).  For example
  711.             batutil {FE foobar.txt hi} would look a file named foobar.txt
  712.       and then search for a line starting with
  713.             :hi
  714.       If the label is not found, then BATUTIL exits with an error message.
  715.       Otherwise the file is processed one line at a time until the next
  716.       line beginning with a : is located.  Lines whose first symbol is a ;
  717.       are ignored (i.e. treated as remarks).
  718.  
  719.             You can combine batch file labels and BATUTIL's labels to
  720.       keep the extra lines to display in the batch file itself.  For
  721.       example, the following could be at the start of a batch file:
  722.             goto codestart
  723.             :echostart
  724.             This line will be echoed
  725.             and this will appear on the next line
  726.             ;but this line is a remark
  727.             The last line doesn't have an explicit CR added
  728.             :codestart
  729.             batutil {FEcho %0 echostart}
  730.       Because BATUTIL will add .bat to a filename if it cannot find
  731.       the file without that, the %0 will be properly interpreted (unless
  732.       you happen to have a file with the same name as the batch file and
  733.       no extension).
  734.  
  735.  
  736.       I.7 BATUTIL's line editor
  737.  
  738.             Four of BATUTIL's commands allow editing of line input: the
  739.       EDenv and PAthedit commands which allow you to edit any
  740.       environmental variable and your path, the USername command which
  741.       prompts for a string to be matched and the $Q/$? subcommands of
  742.       BATUTIL's SET which place information in the environment.  When
  743.       such input is asked for the following edit keys are active
  744.             <Enter> accepts the current string and exits
  745.             <Esc> restores the original value of the string; if that
  746.                original value is empty, <Esc> blanks the line except, in
  747.                that case, <Esc> with a blank line exits and returns an
  748.  
  749.  
  750.     Chapter I:OVERVIEW                                         Page 14
  751.  
  752.  
  753.  
  754.  
  755.                   Documentation for BATUTIL, Version 1.0 
  756.  
  757.  
  758.                empty string
  759.             <Left>, <Right> move the cursor by a character
  760.             <^Left>, <^Right> move the cursor by a word
  761.             <Home>, <End> to the beginning or end of the line
  762.             <Ins> toggles insert mode which starts as overwrite mode; the
  763.                cursor shape indicates what the current mode is
  764.             <Del> and <Bks> do their usual single character functions
  765.             <^X> or <^Y> blanks the entire line
  766.             <^End> blanks to the end of the line
  767.             <^Home> blanks from the start of the line ot the current
  768.                 position.
  769.             <^T> blanks from the cursor position through the next blank
  770.                 space
  771.       In addition, WordStar commands are accepted for most of these
  772.       functions, e.g. ^S is the same as <Left> and the two letter ^QS (or
  773.       ^Q^S) is the same as <Home>.
  774.  
  775.             In situations where the quantity being edited has a prior
  776.       value, that value is displayed when the line editor starts up and
  777.       the cursor is at the end of line.  Hitting an alphanumeric key (as
  778.       opposed to a cursor key) as the first key will blank the original
  779.       value which can be restored with <Esc>.
  780.  
  781.             In each case, the input string has a maximum length which may
  782.       be larger than the edit window on screen.  If it is larger, the
  783.       line editor with scroll horizontally if the cursor moves to the
  784.       start or end of the edit window.
  785.  
  786.             The point is that the editor is quite intuitive and most
  787.       users will have no trouble using it without explicit directions.
  788.  
  789.  
  790.       I.8 The HAltif command
  791.             Command: HAltif
  792.             Parameters: two strings separated by one of =, $g, $l or $q
  793.       with an optional "~ " preceding the strings.
  794.  
  795.             BATUTIL has one rather simple branching command.  HALTIF is
  796.       followed by a condition.  If the condition holds then BATUTIL halts
  797.       execution with that command and exits with an errorlevel of 254.
  798.       If the condition fails then the remainder of the command line is
  799.       processed.  The condition compares two strings with a comparison of
  800.       =, > or <.  SINCE > AND < ARE DOS REDIRECTION SYMBOLS NEVER USE
  801.       THEM IN ACTUAL COMMAND.  As we'll explain in Section III.2, BATUTIL
  802.  
  803.  
  804.     Chapter I:OVERVIEW                                         Page 15
  805.  
  806.  
  807.  
  808.  
  809.                   Documentation for BATUTIL, Version 1.0 
  810.  
  811.  
  812.       has a set of metastring translations which are a superset of those
  813.       used by DOS' prompt command and by STACKEY.  The parameters after
  814.       HAltif are translated using the metastring rules and, in
  815.       particular, $g, $l, $q become >,< and = (you can use = if you
  816.       prefer).
  817.  
  818.             If, after translation, both strings can be interpreted as
  819.       whole numbers less than 134217727 in magnitude, then the comparison
  820.       is done as numbers (so 012 is the same as 12 and 05 is great than
  821.       3).  Otherwise the comparison is done as ASCII strings which
  822.       compares characters one by one and regards a substring as less than
  823.       a longer string (so a05 is smaller than a3).  One or both strings
  824.       can be empty.
  825.  
  826.             You can preface the strings by ~ followed by a space in which
  827.       case the condition is negated, i.e. BATUTIL halts if the condition
  828.       after ~ fails.
  829.  
  830.             Here are some examples
  831.                 {HA $x(comspec)=}
  832.       will halt only if there is no environmental string called comspec
  833.       ($x(...) translates to an environmental variable).
  834.                 {HA $H $l 12}
  835.       halts if the current hour ($H) is smaller than noon.
  836.                 {HA ~ $x(rc)=0}
  837.       will halt unless the environment has a string rc=0 (or rc=00 or
  838.       ...).
  839.  
  840.  
  841.       I.9 Control Break handling
  842.  
  843.             BATUTIL looks especially for the user to press ^Break.  If
  844.       this is pressed during the running of batutil, then the message
  845.             ╒════════════════════╕
  846.             │ Quit BATUTIL(Y/N)? │
  847.             ╘════════════════════╛
  848.       pops up.  If you answer no, then BATUTIL continues where it was
  849.       interrupted.  Otherwise, it pops up a message:
  850.             ╒═══════════════════════════╕
  851.             │ Halt Batch file too(Y/N)? │
  852.             ╘═══════════════════════════╛
  853.       In either event, BATUTIL is then halted.  If you've also answered
  854.       yes to the second question, then BATUTIL will turn DOS Break on and
  855.       place a ^C buffer so the batch file should offer you the chance to
  856.  
  857.  
  858.     Chapter I:OVERVIEW                                         Page 16
  859.  
  860.  
  861.  
  862.  
  863.                   Documentation for BATUTIL, Version 1.0 
  864.  
  865.  
  866.       terminate it.  If you prefer running with Break off, you'll need to
  867.       do that by hand if you use this emergency exit.  This response is to
  868.       ^Break only and NOT also to Ctrl-C.
  869.  
  870.             If you quit BATUTIL with ^Break but elect not to halt the
  871.       batch file, BATUTIL exits with the errorlevel set to 255.
  872.  
  873.             For third party batch files, you may want to turn off ^Break
  874.       to prevent the user from breaking at an inconvenient point.  When
  875.       BATUTIL loads, it checks to see if
  876.             BU^=no
  877.       is in the environment; if it is, then the Ctrl-Break handler is not
  878.       installed, so just include
  879.             set BU^=no
  880.       in the batch file to avoid this premature exit.
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.     Chapter I:OVERVIEW                                         Page 17
  913.  
  914.  
  915.  
  916.  
  917.                    Chapter II:SYSTEM INFORMATION
  918.  
  919.       II.1 Overview
  920.  
  921.             You can use BATUTIL to query the system to get information
  922.       about the current date and time, the current drive, hardware
  923.       information like the number of monitors or printer ports, file
  924.       information like whether a particular file exists on the DOS path.
  925.       Related are a primitive MAKE command which examines two files and
  926.       tells you which is older and a RUN command which will tell you the
  927.       errorlevel that a subsidiary program returns.  You can get the
  928.       information stored in the special environment variable RC or in the
  929.       errorlevel or both.  For example,
  930.             BATUTIL [HO]
  931.       returns the current hour in the errorlevel while
  932.             BATUTIL {HO}
  933.       returns it in both RC and the errorlevel.  Only the last {} command
  934.       on the line has information returned in errorlevel.  If any []
  935.       command is encountered then that is the last command that BATUTIL
  936.       executes before exiting.  Except for the internal FDir command, all
  937.       commands discussed in this chapter are dual mode []/{} commands.
  938.  
  939.             If an intermediate result is stored in an environmental
  940.       variable like RC, you can have it placed in the errorlevel with the
  941.       ERrorlevel command as in
  942.             batutil {HO}{EC The current hour is $x(rc)}[ER $x(rc)]
  943.       The $x syntax is discussed in Section III.1.
  944.  
  945.             Many commands come in pairs like #Disk and @Disk starting
  946.       with # or @.  Typically, # refers to total and @ to free so that
  947.             BATUTIL [#D]
  948.       places in the errorlevel the total space on the default drive and
  949.             BATUTIL [@D]
  950.       the amount of free space.  As in STACKEY, the left round parenthesis,
  951.       (, is a synonym for @ and the right round parenthesis, ), for #.  Thus
  952.       the last command could also be
  953.             BATUTIL [(D]
  954.  
  955.             Commands have full names such as HOUR but any name can be
  956.       abbreviated by using two or more letters as in HO or HOU.  To
  957.       emphasize this, we'll write the commands as HOur but that does not
  958.       mean you have to type the command with that capitalization.
  959.       BATUTIL's command interpreter is not case sensitive.  When you want
  960.       to squeeze a lot on the command line, you'll want to use the two
  961.       letter abbreviation.
  962.  
  963.  
  964.  
  965.  
  966.     Chapter II:SYSTEM INFORMATION                              Page 18
  967.  
  968.  
  969.  
  970.  
  971.                   Documentation for BATUTIL, Version 1.0 
  972.  
  973.  
  974.             You'll often want to use the SEt command and metastring
  975.       expansion in connection with or instead of the commands of this
  976.       chapter.  The SEt command is described in Section V.3 and
  977.       metastrings in Section III.1.  As examples of what we mean,
  978.             BATUTIL {#comm}{set comm=$x(rc)}{#prn}{set prn=$x(rc)}
  979.       would place the number of comm ports in the environment as
  980.             comm=nn
  981.       and then the number of printers as
  982.             prn=nn
  983.       but one wouldn't use
  984.             BATUTIL {HO}{set hour=$x(rc)}
  985.       since there is a metastring for the current hour and one could
  986.       just as well use
  987.             BATUTIL {set hour=$H}.
  988.  
  989.  
  990.       II.2 Time
  991.             Commands: HOur, MInute, WEekday, DAte, MOnth, YEar
  992.  
  993.             You can return information on the time and date in the
  994.       errorlevel as follows
  995.             HOur the hour in military time from 0 to 23
  996.             MInute the number of minutes past the hour from 0 to 59
  997.             WEekday the day of the week from 0=Sunday to 6=Saturday
  998.             DAte the day of the month from 1 to 31
  999.             MOnth the number of the month from 1 to 12
  1000.             YEar the number of years since 1980 from 0 to 19 so in 1988
  1001.       this would return 8.
  1002.  
  1003.  
  1004.       II.3 Operating System and Memory Information
  1005.             Commands: DOs, DRive, LIm, HImem, CArousel, DView, OView,
  1006.       #Mem, @Mem, #Lim, @Lim, #Xtended, @Xtended, #Env, @Env, #Disk,
  1007.       @Disk
  1008.  
  1009.             Parameters: For #D and @D, no parameter picks default drive or
  1010.       you can give a drive letter.  For DOs, nothing or "4"
  1011.  
  1012.             You can return the following information about the operating
  1013.       environment:
  1014.  
  1015.             DOs returns the DOS Version times 10 rounded downwards so DOS
  1016.       2.1 would return 21 and DOS 3.21 would return 32.
  1017.  
  1018.  
  1019.  
  1020.     Chapter II:SYSTEM INFORMATION                              Page 19
  1021.  
  1022.  
  1023.  
  1024.  
  1025.                   Documentation for BATUTIL, Version 1.0 
  1026.  
  1027.  
  1028.             "DOs 4" returns information about the program 4DOS from JP
  1029.       Software, an alternative to Command.com.  If a swapping version of
  1030.       4DOS is loaded anywhere in memory, then the value 10 times the 4DOS
  1031.       version number is returned; otherwise the value 0 is returned. This
  1032.       requires 4DOS Version 2.1 or later.
  1033.  
  1034.             DRive returns the current drive with 0=A, 1=B, ...., 25=Z.
  1035.       This is the drive as DOS reports it so if SUBST is in effect, the
  1036.       subst letter will be used.
  1037.  
  1038.             LIm returns 0 if no EMS manager is installed and the Version
  1039.       times 10 rounded downwards so to check whether an EMS 4.0 driver is
  1040.       installed you'd use
  1041.             BATUTIL [LI]
  1042.             if errorlevel 40 .....
  1043.  
  1044.             HImem returns 0 if no XMS manager setting up the Microsoft
  1045.       Himem area is installed and a 1 if such a manager is installed.
  1046.       Examples of XMS managers are Himem, which comes with some versions
  1047.       of Windows and DOS, 386 to the max and QEMM/386.
  1048.  
  1049.             CArousel returns 0 if SoftLogic's SOFTWARE CAROUSEL is not
  1050.       installed and otherwise returns the partition number from 1 to 12 (1 to
  1051.       10 with Carousel version prior to 3.0).
  1052.  
  1053.             DView returns 0 if Quarterdeck's DESQVIEW is not installed
  1054.       and otherwise returns the partition number from 1 to 255.
  1055.  
  1056.             OView returns 0 if Sunny Hill's OMNIVIEW is not installed and
  1057.       otherwise returns the partition number from 1 to 10.
  1058.  
  1059.             You can also get information about memory and disk resources:
  1060.  
  1061.             #Mem returns the total conventional memory in units of 4K
  1062.       from 0 to 160 (160 means 640K); the amount is rounded down.  If you
  1063.       have an appropriate program/hardware combination to have more than
  1064.       640K of conventional memory (EEMRAM, 386 to the max or QEMM, for
  1065.       example), then the number returned may be more than 640K but it
  1066.       will never be more than 184.
  1067.  
  1068.             @Mem returns the free conventional memory in units of 4K
  1069.  
  1070.             #Lim returns 0 if no EMS memory is present; otherwise, it
  1071.       returns the total EMS memory in units of 64K from 0 to 199.  This
  1072.  
  1073.  
  1074.     Chapter II:SYSTEM INFORMATION                              Page 20
  1075.  
  1076.  
  1077.  
  1078.  
  1079.                   Documentation for BATUTIL, Version 1.0 
  1080.  
  1081.  
  1082.       is rounded down and with 12736K or more of EMS, 199 is returned.
  1083.  
  1084.             @Lim returns 0 if no EMS memory is present; otherwise, it
  1085.       returns the free EMS memory in units of 16K from 0 to 199.  This
  1086.       is rounded down and with 3184K or more of free EMS, 199 is
  1087.       returned.
  1088.  
  1089.             #Xtended returns 0 if no extended memory is present;
  1090.       otherwise, it returns the total extended memory in units of 64K
  1091.       from 0 to 199.  This is rounded down and with 12736K or more of
  1092.       extended memory, 199 is returned.
  1093.  
  1094.             @Xtended returns 0 if no extended memory is present;
  1095.       otherwise, it returns the "free" extended memory in units of 16K
  1096.       from 0 to 199.  This is rounded down and with 3184K or more of
  1097.       extended memory, 199 is returned.   Because there is no standard
  1098.       for extended memory usage, BATUTIL is not totally accurate in its
  1099.       count of free extended memory.  It subtracts from the total
  1100.       available the amount used by VDISK and VDISK compatible programs.
  1101.  
  1102.             #Env returns the total amount of environment space in units
  1103.       of 16 bytes.  See Section V.1 for a discussion of the DOS
  1104.       environment area.  The answer can be from 0 to 199 with 199
  1105.       corresponding to 3184 or more bytes.
  1106.  
  1107.             @Env returns the free environment space in units of 1 byte.
  1108.       The answer can be from 0 to 199 with the later indicated 199 or
  1109.       more.
  1110.  
  1111.             #Disk returns the total amount of disk space.  An optional
  1112.       parameter is allowed of a letter.  If no parameter is given, then
  1113.       the response is for the default drive.  For drives A and B the
  1114.       errorlevel is space in units of 8K from 0 to 199 rounded down.  If
  1115.       there is more than 1592K (not possible on currently available
  1116.       diskettes) a value of 199 is returned.  For drives other than A, B
  1117.       the amount is in units of 256K from 0 to 199.  For drives of 49.75
  1118.       Meg or more (possible only under DOS versions greater than 3.30 or
  1119.       with special software), 199 is returned.  If an invalid drive
  1120.       letter is given, the errorlevel is set to 232.  If there is a
  1121.       syntax error such as asking for {#D 7}, the errorlevel is set to
  1122.       208.
  1123.  
  1124.             @Disk returns the amount of free space on a disk drive with
  1125.       the same parameters and errorlevels for errors as #D.  For any
  1126.  
  1127.  
  1128.     Chapter II:SYSTEM INFORMATION                              Page 21
  1129.  
  1130.  
  1131.  
  1132.  
  1133.                   Documentation for BATUTIL, Version 1.0 
  1134.  
  1135.  
  1136.       drive, the amount free is reported in units of 8K from 0 to 199.
  1137.       With more than 1592K free, the value returned is 199.   Please note
  1138.       that @D and #D use different units.
  1139.  
  1140.  
  1141.       II.4 Console Information
  1142.             Commands: #Terminal, @Terminal, #Vmode, #Whichmon, #Altmon,
  1143.       @Ansi, #Keyboard, #Rodent
  1144.  
  1145.             BATUTIL will give you information about the system monitors
  1146.       and keyboards as follows:
  1147.  
  1148.             #Terminal with no parameter returns the number of monitors
  1149.       you have, either 1 or 2.  With the parameter R (or r or even Rows if
  1150.       you prefer), it returns the number of rows on the screen.  IBM EGAs
  1151.       support 43 rows as well as 25 and VGAs support 50.  Many superVGAs
  1152.       support 33, 36 or 60 rows.  UltaVision also supports non-standard
  1153.       numbers of rows.  Similar UltraVision and some SuperEGA or
  1154.       SuperVGAs support 120 or 132 columns and #T with the C parameter
  1155.       returns the number of columns.  Some programs require 1 less than
  1156.       the number of rows so S, for Special as a parameter returns that.
  1157.  
  1158.             @Terminal returns the currently active monitor: 0 if mono and
  1159.       1 if color (or CGA compatible B/W like the old style Compaq
  1160.       monitors).
  1161.  
  1162.             #Vmode returns the current video mode as reported by int 10H.
  1163.  
  1164.             #Whichmon returns the type of the current monitor according
  1165.       to the following table:
  1166.                1 = monochrome  (old style MDA)
  1167.                2 = cga color
  1168.                4 = ega color
  1169.                5 = ega mono
  1170.                6 = professional graphics controller
  1171.                7 = vga mono
  1172.                8 = vga color
  1173.               11 = mcga mono
  1174.               12 = mcga color
  1175.               21 = hercules mono
  1176.               22 = hercules monochrome plus (with RAM font)
  1177.               23 = hercules Incolor
  1178.               99 = unknown
  1179.       If this ordering seems bizarre to you, it does to us also!  The
  1180.  
  1181.  
  1182.     Chapter II:SYSTEM INFORMATION                              Page 22
  1183.  
  1184.  
  1185.  
  1186.  
  1187.                   Documentation for BATUTIL, Version 1.0 
  1188.  
  1189.  
  1190.       numbers below 20 are taken from the official "Display Combination
  1191.       Code" in the IBM PS/2 computer BIOS and who are we to argue with
  1192.       IBM.
  1193.  
  1194.             #Altmon returns information about the second monitor if you
  1195.       have one.  Allowed values are 0 (which indicates no second
  1196.       monitor) and the numbers above.
  1197.  
  1198.             @Ansi returns 1 if an ANSI.SYS compatible console driver is
  1199.       installed and 0 otherwise.
  1200.  
  1201.             #Keyboard will return whether an "enhanced" keyboard is
  1202.       attached (the enhanced keyboard is the 101 key keyboard with the
  1203.       function keys across the top and the CapsLock where everyone knows
  1204.       the Ctrl key should be).  A 0 response indicates a 84 key keyboard
  1205.       and a 1 the enhanced keyboard.  Actually, BATUTIL is not testing
  1206.       the keyboard but rather the presence of BIOS support for the
  1207.       enhanced keyboard.
  1208.  
  1209.             #Rodent returns 1 if a Microsoft compatible mouse is found and 0
  1210.       otherwise.
  1211.  
  1212.  
  1213.       II.5 Hardware Information
  1214.             Commands: #Intel, @Intel, #Prn, @Prn, #Comm, #Game, #Floppy,
  1215.       @Floppy
  1216.             Parameters: For @P, printer number from 1 to 3; no parameter
  1217.       picks LPT1.
  1218.  
  1219.             #Intel tests what CPU you have and reports as follows:
  1220.               0 = 8086/8088
  1221.               1 = 80186
  1222.               2 = 80286
  1223.               3 = 80386
  1224.              20 = NEC V20/V30
  1225.  
  1226.             @Intel tests what kind of math coprocessor that you have and
  1227.       reports as follows:
  1228.               0 = no math coprocessor
  1229.               1 = 8087
  1230.               2 = 80287
  1231.               3 = 80387
  1232.  
  1233.  
  1234.  
  1235.  
  1236.     Chapter II:SYSTEM INFORMATION                              Page 23
  1237.  
  1238.  
  1239.  
  1240.  
  1241.                   Documentation for BATUTIL, Version 1.0 
  1242.  
  1243.  
  1244.             For technical reasons, only one occurrence of #I/@I per
  1245.       running of BATUTIL is allowed; you'll need to place @I and #I on
  1246.       separate lines if you want both.  If two occurrence are found on
  1247.       the command line, BATUTIL will exit with a syntax error 210.
  1248.  
  1249.             #Prn reports the number of printers attached to your system
  1250.       (or more precisely the number that DOS thinks you have attached)
  1251.  
  1252.             @Prn returns error information for one of your printers.  You
  1253.       can specify a printer number or, if none is given, LPT1 will be
  1254.       tested.  The number returned means:
  1255.               0 = printer status OK
  1256.               1 = paper out error
  1257.               2 = I/O error
  1258.               3 = Timeout error
  1259.               4 = invalid printer
  1260.               5 = other printer error
  1261.       If you have a print spooler installed, you'll get a response of 0
  1262.       even if the printer is offline or out of paper.
  1263.  
  1264.             #Comm returns the number of serial ports that you have; with
  1265.       more than 2 ports present, the method may not be reliable depending
  1266.       on how your non-DOS ports are added on.
  1267.  
  1268.             #Game returns the number of game ports that you have (or at
  1269.       least that BIOS thinks you have as stored in the equipment byte).
  1270.  
  1271.             #Floppy returns the number of Diskette drives you have
  1272.  
  1273.             @Floppy returns the following information
  1274.               0 = you have none or more than 1 diskette drive
  1275.               1 = you have a single diskette drive which is currently
  1276.       logical drive A
  1277.               2 = you have a single diskette drive which is currently
  1278.       logical drive B
  1279.  
  1280.  
  1281.       II.6 File information
  1282.             Commands: EXist, CHeck, NUmberfiles
  1283.             Parameters: for EXist - filename (no wildcards)
  1284.                         for CHeck - pathname with or without trailing \
  1285.                         for NUmberfiles - filespec(s) with wildcards
  1286.             Internal Command: FDir
  1287.  
  1288.  
  1289.  
  1290.     Chapter II:SYSTEM INFORMATION                              Page 24
  1291.  
  1292.  
  1293.  
  1294.  
  1295.                   Documentation for BATUTIL, Version 1.0 
  1296.  
  1297.  
  1298.             BATUTIL has a number of commands that will return information
  1299.       about files on disk.  Each of these commands must have a parameter
  1300.       describing the filespec of the file or path you want information
  1301.       about.  They will only take a single parameter except for NUmberfiles.
  1302.  
  1303.             EXist is a more powerful version of DOS' "if exist" command.
  1304.       If a filename is given with no path or drive, the responses are
  1305.             0 = the file exists in the default directory or the filename
  1306.       is the name of a device loaded in your config.sys (see below)
  1307.             1 = the file does not exist in the current directory but it
  1308.       does exist somewhere on the PATH.  The directory can be returned in
  1309.       an environmental variable; see the discussion of FDir below.
  1310.             2 = the file does not exist in the path
  1311.             codes above 200 indicate DOS, syntax or environmental errors;
  1312.       see Chapter VIII.
  1313.  
  1314.             If a path or drive is given as in "batutil {EX C:foobar.txt}"
  1315.       or "batutil {EX \bin\foobar.txt}", then the responses are
  1316.             0 = the file exists in the specified drive and/or directory
  1317.             2 = the file does not exist in the specified drive and/or
  1318.       directory
  1319.             9 = the path given is not a valid path
  1320.             codes above 200 indicate DOS, syntax or environmental errors;
  1321.       see Chapter VIII.
  1322.  
  1323.             EX does not interpret wildcards, that is if you look for a
  1324.       file named foo*.* as in "batutil {ex foo*.*}", then BATUTIL will
  1325.       look precisely for a file with that exact name and not find it.
  1326.  
  1327.             If a filename with no explicit path is entered as the
  1328.       parameter for EX and the file is not found in the current
  1329.       directory, then the DOS path is searched for it and optionally, the
  1330.       directory where it is found is placed in the environment.  By
  1331.       default, the name FDIR is used so that if foobar.txt existed in
  1332.       directory C:\bin which was in your path, then after running
  1333.             batutil {EX foobar.txt}
  1334.       RC would have the value 1 and FDIR the value C:\bin, that is a DOS
  1335.       SET (or batutil {envrep}) will include
  1336.             FDIR=C:\BIN
  1337.             RC=1
  1338.       The FDir command allows you to change where this directory name is
  1339.       stored.  If no new name is given then the directory name is not
  1340.       stored so
  1341.             batutil {FD}{EX foobar.txt}
  1342.  
  1343.  
  1344.     Chapter II:SYSTEM INFORMATION                              Page 25
  1345.  
  1346.  
  1347.  
  1348.  
  1349.                   Documentation for BATUTIL, Version 1.0 
  1350.  
  1351.  
  1352.       would not store the name C:\BIN anywhere while
  1353.             batutil {FD foo}{EX foobar.txt}
  1354.       would store the string
  1355.             FOO=C:\BIN
  1356.       You might want to use this directory name in a way that requires a
  1357.       backslash; for example you might want to copy the file.  Just
  1358.       adding the backslash by hand won't work if the directory is the
  1359.       root (which already ends in a backslash).  If you use FDIR to
  1360.       define a variable which begins with a \, then a trailing backslash
  1361.       is added.  Thus
  1362.             batutil {FD \foo}{EX foobar.txt}
  1363.       would store the string
  1364.             \FOO=C:\BIN\
  1365.       and you could then use the command
  1366.             copy %\foo%foobar.txt A:
  1367.       FDIR is also used by the $f file picklist discussed in Section V.5.
  1368.  
  1369.             If your machine has a config.sys file, it likely loads
  1370.       various device drivers with the "device=" command.  In addition,
  1371.       DOS sets up various devices like NUL, CON, PRN and LPT2.  Some of
  1372.       the devices have explicit names.  For example, any EMS driver will
  1373.       call its device EMMXXXX0, the memory manager 386 to the Max calls
  1374.       its device 386MAX$$ and the Microsoft Himem program loads a device
  1375.       called XMSXXXX0.  If you use DOS' "if exist" it will recognize a
  1376.       device in any directory, so, for example
  1377.             if exist \somepath\nul echo hi
  1378.       will echo if and only if the directory \somepath\ exists.  In the
  1379.       same way, BATUTIL {EX ...} will return a code of 0 if ... is a
  1380.       device.  But to distinguish devices from files, it does an extra
  1381.       check to see if the specified file is a device.  If it is, it sets
  1382.       FDIR (or whatever you've replaced fdir by with the FDIR command) to
  1383.       the value IS_A_DEVICE.
  1384.  
  1385.             CHeck will check whether a path exists and reply 0 if it does
  1386.       and 9 if it does not.  You can include a tailing backslash or not
  1387.       as you wish.
  1388.  
  1389.             If you want a batch file to act differently depending on
  1390.       whether A: has a diskette in it or not, use
  1391.             BATUTIL Q {CH A:\}
  1392.       which will return errorlevel 0 if there is a diskette and
  1393.       errorlevel 230 (drive not ready) if not.  If you used
  1394.             if exist A:\nul
  1395.       instead and no diskette were there, the batch file would halt with
  1396.  
  1397.  
  1398.     Chapter II:SYSTEM INFORMATION                              Page 26
  1399.  
  1400.  
  1401.  
  1402.  
  1403.                   Documentation for BATUTIL, Version 1.0 
  1404.  
  1405.  
  1406.       an Abort, Retry, Fail message.
  1407.  
  1408.             NUmberfiles takes a filespec with wildcards and tells you how
  1409.       many files match in the default directory match that filespec, for
  1410.       example
  1411.             BATUTIL {NU C:\bin\*.*}
  1412.       would tell you the total number of files in that directory.  The
  1413.       answer will be between 0 and 199; the answer 199 indicates that
  1414.       there are 199 or more matching files.  NU will take more than one
  1415.       file spec so that
  1416.             BATUTIL {NU C:\bin\*.com C:\bin\*.exe}
  1417.       would tell you the total number of executables in C:\bin.
  1418.  
  1419.  
  1420.       II.7 The RUn Command
  1421.             Command: RUn
  1422.             Parameter: program name
  1423.  
  1424.             BATUTIL has a command that will let you run another program
  1425.       and get the errorlevel that program exits with recorded in the
  1426.       environment as the value of RC.  The syntax is
  1427.             BATUTIL {RU programname}
  1428.       programname can include a path if you wish.  Like DOS, BATUTIL will
  1429.       ignore any extension that you give and first try a COM file and
  1430.       then an EXE file.  Afterward the program has run, RC will be set to
  1431.       the errorlevel of programname.  A typical application of this would
  1432.       be to get the errorlevel reported on screen by
  1433.             BATUTIL {RU programname}{EC $x(RC)}
  1434.  
  1435.             For this purpose, a stand alone program called WHATEL is
  1436.       provided.  Just type in
  1437.             WHATEL programname
  1438.       and the program will report the errorlevel and the time it took
  1439.       programname to run.  This time is rounded up in units of 55
  1440.       milliseconds (the smallest unit of time one can measure without
  1441.       reprogammming the PC's internal clock) so that time differences of
  1442.       .06 seconds are insignificant.
  1443.  
  1444.             BATUTIL {RU ...} takes about 175K to run which is that much
  1445.       less for "programname".  WHATEL takes less than 17K.
  1446.  
  1447.             There is a slight difference between how BATUTIL {RU ...} and
  1448.       WHATEL work.  The former searches for a COM or EXE executable
  1449.       binary file in the current directory or on the path.  It will yield
  1450.  
  1451.  
  1452.     Chapter II:SYSTEM INFORMATION                              Page 27
  1453.  
  1454.  
  1455.  
  1456.  
  1457.                   Documentation for BATUTIL, Version 1.0 
  1458.  
  1459.  
  1460.       an error message if you use a batch file name, DOS internal command
  1461.       or bad command name.  The philosophy is that since batch files
  1462.       don't yield errorlevels, it is an error to try RUn with one.  But
  1463.       since WHATEL is also a timing utility, it might be used for batch
  1464.       files, internal commands or even to time a bad command.  So, if
  1465.       WHATEL cannot locate a suitable COM or EXE file, it passes your
  1466.       command to DOS to see if DOS can make sense if it.  In that case
  1467.       instead of reporting: "Errorlevel returned by ... was ..." WHATEL
  1468.       reports "...run from a shell of DOS".
  1469.  
  1470.  
  1471.       II.8 TOdayfile and MAkefile
  1472.             Commands: TOdayfile, MAkefile
  1473.             Parameters: For TOdayfile: either a filename or an hour and
  1474.                            a filename; for MAkefile: two filenames
  1475.  
  1476.             The TOdayfile command is intended to tell you whether a given
  1477.       file has today's date.  As we'll explain in Chapter VI, it is
  1478.       intended for use in a batch file, usually an autoexec.bat file, to
  1479.       make sure that some operation is only done once a day.  In the
  1480.       simplest form, the syntax is
  1481.             BATUTIL {TO filename}
  1482.       and the responses are
  1483.             0 = the file has today's date
  1484.             1 = the file exists and doesn't have today's date
  1485.             2 = file not found
  1486.             9 = invalid path
  1487.             above 200; DOS and syntax errors as in Chapter VIII; allowed
  1488.       values are 230, 231  (for DOS error) or 204 - 207 (for syntax
  1489.       errors).
  1490.  
  1491.             If you wish, TO will take an optional numeric parameter as
  1492.       its first parameter, i.e. with syntax
  1493.             BATUTIL {TO hour filename}
  1494.       where hour is between 0 and 23.  This parameter is used if you'd
  1495.       like the day to begin at a time other than midnight (0 is therefore
  1496.       a redundant choice put in only for completeness).  For example if
  1497.       you type in
  1498.             BATUTIL {TO 5 test.dat}
  1499.       then BATUTIL will look at days beginning at 5 in the morning and
  1500.       see whether test.dat and the current date/time are on the same
  1501.       "day".  Thus if test.dat was made yesterday at 8:15 AM the above
  1502.       command would return an errorlevel of 0 if the current time is
  1503.       before 5 AM and an errorlevel of 1 if after 5 AM.  This will
  1504.  
  1505.  
  1506.     Chapter II:SYSTEM INFORMATION                              Page 28
  1507.  
  1508.  
  1509.  
  1510.  
  1511.                   Documentation for BATUTIL, Version 1.0 
  1512.  
  1513.  
  1514.       prevent an action from happening if you stay up late at night and
  1515.       don't want to think of that as a new day.
  1516.  
  1517.             MAkefile requires two file names which we'll call file1 and
  1518.       file2.  The errorlevel returned is as follows:
  1519.             0 = file2 not found
  1520.             1 = file2 is strictly older
  1521.             2 = file1 not found
  1522.             3 = file1 older or the same age as file2
  1523.             9 = path not found
  1524.             above 200; DOS and syntax errors as in Chapter VIII; allowed
  1525.                 values are 230, 231 (for DOS disk errors) and 204,205
  1526.                 (for syntax error)
  1527.       This choice is made because if file2 doesn't exist or is older, one
  1528.       will want to take an action like compile something or backup
  1529.       something else.
  1530.  
  1531.  
  1532.       II.9 The ERrorlevel command
  1533.  
  1534.             You can set the errorlevel to a prescribed number between 0
  1535.       and 199 with the ERrorlevel command.  ER must be followed by a
  1536.       number or by a metastring beginning with $ that translate into a
  1537.       number or by $$ followed by a hex number.  If, after metastring
  1538.       translation, the parameter is not a number, BATUTIL exits with the
  1539.       errorlevel set to 206 (and an error message if Verbose mode is on).
  1540.       If the number is less than 0, 0 is returned and if greater than 199,
  1541.       then 199 is returned.
  1542.  
  1543.             For example
  1544.             batutil [ER $H]
  1545.       is the same as
  1546.             batutil [HO]
  1547.       and
  1548.             batutil ....[ER $x(RC)]
  1549.       would set the exit errorlevel to the value of RC set by an earlier
  1550.       command.
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.     Chapter II:SYSTEM INFORMATION                              Page 29
  1561.  
  1562.  
  1563.  
  1564.  
  1565.                    Chapter III: DISPLAY TOOLS
  1566.  
  1567.  
  1568.       III.1 Overview
  1569.  
  1570.             One of the most important aspects of a batch files on which
  1571.       DOS is woefully inadequate is communicating with the batch file
  1572.       user.  In this chapter, we'll discuss enhancements to better
  1573.       display messages giving you control on colors, on where the messages
  1574.       are displayed and allowing you easily place system information like
  1575.       the current drive in your messages.  BATUTIL also provides 10 sounds
  1576.       and 10 tunes with you can use to communicate with the batch file user.
  1577.       In the next chapter we'll discuss the tools that BATUTIL gives you to
  1578.       get input from the user.  One of those methods pops up a menu and
  1579.       another pops up a file list and so they also involve display.
  1580.  
  1581.             In Section III.2, we'll discuss some automatic translation
  1582.       that gets done when you ask BATUTIL to display a string.  This
  1583.       translation mechanism is also relevant to the SEt command discussed
  1584.       in Section V.3.
  1585.  
  1586.             By default, BATUTIL displays by writing directly to the
  1587.       screen but as we'll discuss in Section III.7, you can instruct
  1588.       BATUTIL to use standard output if you wish to redirect the ECho
  1589.       command to a file or printer.
  1590.  
  1591.  
  1592.       III.2 Metastring Translation
  1593.             Commands: $Translate, ^Translate
  1594.             Parameters: - to turn off
  1595.  
  1596.             The DOS PROMPT command supports a set of what the DOS manual
  1597.       calls metastrings; something like $p is translated into the
  1598.       current path name.  STACKEY extended this set of metastrings.
  1599.       BATUTIL uses all the STACKEY metastrings and adds a few extra ones
  1600.       to accommodate its special structure.  This metastring translation
  1601.       takes place for the ECho and PRetty commands discussed in this
  1602.       chapter, the MEnu command of the next chapter and the SEt command
  1603.       of Chapter V.  As we'll explain you can tell BATUTIL not to make
  1604.       the translation if you wish.
  1605.  
  1606.             Here are the PROMPT metastrings, all of which are used by
  1607.       BATUTIL:
  1608.                $$              The character "$"
  1609.                $t              The time in HH:MM:SS.hh format
  1610.                $d              The date in DAY MM-DD-YYYY format
  1611.                                         e.g. Tue 9-30-1986
  1612.  
  1613.  
  1614.     Chapter III: DISPLAY TOOLS                                 Page 30
  1615.  
  1616.  
  1617.  
  1618.  
  1619.                   Documentation for BATUTIL, Version 1.0 
  1620.  
  1621.  
  1622.                $p              The current path in full, e.g. C:\BIN\FOO
  1623.                $v              The current DOS version
  1624.                $n              The current default drive
  1625.                $g              The character ">"
  1626.                $l              The character "<"
  1627.                $b              The character "|"
  1628.                $q              The character "="
  1629.                $h              The backspace
  1630.                $e              The ESCape
  1631.                $_              CR/LF (i.e. <Enter> followed by Ctrl-<Enter>
  1632.       and the special STACKEY metastrings which are used by BATUTIL:
  1633.                $P              same as $p in the root dir and as $p\ elsewhere
  1634.                $T              time in HHMM format
  1635.                $M              month in MM format, e.g. 09
  1636.                $D              day in DD format, e.g. 03
  1637.                $Y              year in YY format, e.g. 86 in 1986 and 01
  1638.       in 2001
  1639.                $W              day of the week in English, e.g. Sunday
  1640.                $E              the date in English, e.g. February 18, 1988
  1641.                $H              hour from 00 to 23
  1642.                $m              minute from 0 to 59
  1643.       and BATUTIL will make the translation of ^ to indicate a control
  1644.       character, e.g. ^A and ^B will display happy faces.
  1645.  
  1646.             In addition, there are several metastrings special to
  1647.       BATUTIL starting with some simple translations:
  1648.                $S              a space
  1649.                $^              The character ^
  1650.                $(              The character {
  1651.                $)              The character }
  1652.                $`              The character [
  1653.                $'              The character ]
  1654.  
  1655.             The $S is necessary in situations where BATUTIL uses spaces
  1656.       to separate parameters and you want a space in a string.  For
  1657.       example
  1658.             BATUTIL {ME a b c}
  1659.       would pop up a menu of the form
  1660.                                     ╒═══╕
  1661.                                     │ a │
  1662.                                     │ b │
  1663.                                     │ c │
  1664.                                     ╘═══╛
  1665.       while
  1666.  
  1667.  
  1668.     Chapter III: DISPLAY TOOLS                                 Page 31
  1669.  
  1670.  
  1671.  
  1672.  
  1673.                   Documentation for BATUTIL, Version 1.0 
  1674.  
  1675.  
  1676.             BATUTIL {ME a$Sb c}
  1677.       would pop up a menu of the form
  1678.                                     ╒═════╕
  1679.                                     │ a b │
  1680.                                     │ c   │
  1681.                                     ╘═════╛
  1682.  
  1683.             $(, $), $` and $' are needed because {,},[,] are command
  1684.       separators for BATUTIL and their use in the middle of a display
  1685.       string would likely produce something other than what you want.
  1686.  
  1687.             BATUTIL will do filename parsing; if ... is a filename, then
  1688.               $a(...) = path of ... without trailing backslash
  1689.               $A(...) = path of ... with trailing backslash added
  1690.               $B(...) = name of ...
  1691.               $C(...) = extension of ....
  1692.       Note that these commands are case sensitive.  For example
  1693.               $A(C:\bin\batfiles\foobar.bat) = C:\bin\batfiles\
  1694.               $a(C:\bin\batfiles\foobar.bat) = C:\bin\batfiles
  1695.               $B(C:\bin\batfiles\foobar.bat) = foobar
  1696.               $C(C:\bin\batfiles\foobar.bat) = bat
  1697.       Metastring translation is not done on the string in ... with one
  1698.       crucial exception.  The $x/$X environmental substitution is made.  The
  1699.       most common use of these filename parsers would be to use the $f
  1700.       command to have the user choose a file from a popup list which you
  1701.       could then parse, e.g.
  1702.             BATUTIL {EC Pick file}{SET foo=$f fooext=$C($x(foo))}
  1703.  
  1704.             You can access environmental variables with either $x(var) or
  1705.       $X(var) where "var" is the name of an environment variable.  $X
  1706.       will first translate the string using metastring translation while
  1707.       $x will not.  Thus if your environment includes
  1708.                FOO=$p
  1709.       the DOS level command
  1710.             BATUTIL {EC $x(foo)}
  1711.       would display the string $p on the screen while
  1712.             BATUTIL {EC $X(foo)}
  1713.       would display the current directory.  You can have a $x or $X as
  1714.       part of the variable being translated by $X in which case there is
  1715.       recursion.  To avoid a crash if an infinite loop results as it
  1716.       would if foo1=$X(foo2) and foo2=$X(foo1), $X's are only translated
  1717.       60 times at which point no further translation is done. When
  1718.       preparing batch files for third parties, use caution with $X.  If
  1719.       there is a metastring syntax error (like using $j, an improper
  1720.  
  1721.  
  1722.     Chapter III: DISPLAY TOOLS                                 Page 32
  1723.  
  1724.  
  1725.  
  1726.  
  1727.                   Documentation for BATUTIL, Version 1.0 
  1728.  
  1729.  
  1730.       metastring) in foo, then use of $X(foo) will cause BATUTIL to exit
  1731.       with error 209.
  1732.  
  1733.             There are two subtle differences between the $x command and using
  1734.       DOS' %...% command.  There is no effective difference between
  1735.             BATUTIL {EC $x(foo)}
  1736.       and
  1737.             BATUTIL {EC %foo%}
  1738.       but if your environment starts out with
  1739.                FOO=initial
  1740.       then
  1741.             BATUTIL {SET foo=final}{EC $x(foo)}
  1742.       would display "final" on the screen while
  1743.             BATUTIL {SET foo=final}{EC %foo%}
  1744.       would display "initial" on the screen.  In addition, DOS does the
  1745.       translation of %foo% before passing the command onto BATUTIL which
  1746.       could bring the command line above the maximum 127 characters
  1747.       supported by DOS while BATUTIL only expands $x(foo) after getting
  1748.       the command line and there is not the same limitation.
  1749.  
  1750.             In the SEt command, $Q, $? and $f have special meaning; see the
  1751.       discussion Sections V.4 and V.5.   In connection with the {GEtkey
  1752.       WAit} command, $L sets the location of a time countdown if used in
  1753.       an ECho or PRetty command.  See the discussion in Section IV.5
  1754.  
  1755.             If you wish to turn off metastring translation, you can with
  1756.       the commands
  1757.             $T -    to turn off $ translation
  1758.             $T      to turn $ translation back on
  1759.             ^T -    to turn off ^ translation
  1760.             ^T      to turn ^ translation back on
  1761.       It is important to bear in mind that BATUTIL has no memory from one
  1762.       running to the next so that
  1763.             BATUTIL {$T -}{EC $p}{$T}{EC $q$p}
  1764.       would display
  1765.                 $p=C:\BIN
  1766.       if BIN were your current directory but
  1767.             BATUTIL {$T -}
  1768.             BATUTIL {EC $p}{$T}{EC $q$p}
  1769.       would display
  1770.                 C:\BIN=C:\BIN
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.     Chapter III: DISPLAY TOOLS                                 Page 33
  1777.  
  1778.  
  1779.  
  1780.  
  1781.                   Documentation for BATUTIL, Version 1.0 
  1782.  
  1783.  
  1784.       III.3 BATUTIL's ECho command
  1785.             Commands: ECho, ATtribute, MNattribute, CLs, EOline
  1786.             Parameters: EC takes the string to echo
  1787.                        AT, MN take a hex byte.  AT T is also legal; see
  1788.                              Section IV.5
  1789.                        EOline takes an optional parameter of +
  1790.  
  1791.             You can echo a string to the screen with the FEcho command
  1792.       discussed in Section III.5 below or with
  1793.                BATUTIL {EC string}
  1794.       The reasons to use BATUTIL's echo rather than DOS' echo are the
  1795.       following
  1796.             -  metastring translation takes place with BATUTIL
  1797.             -  there is not an automatic CR (which means you'll need to
  1798.       remember to add $_) but you can place several lines of text on one
  1799.       echo line (subject to DOS' 127 character limitation) by using $_
  1800.             -  if you use BATUTIL's ECho command between two cursor
  1801.       location commands, BATUTIL will only be loaded once while if you
  1802.       use DOS' echo it will not
  1803.             -  as we'll explain, BATUTIL gives you color control
  1804.  
  1805.             BATUTIL stores away two color combinations that it uses: one
  1806.       for color screens which defaults to yellow on blue and one for
  1807.       monochrome screens which defaults to dull foreground (attribute
  1808.       07 hex).  This attribute is used in several places:
  1809.             it is used by the ECho command
  1810.             it is used to set the colors by the CLs command
  1811.             it is used for shadows in the MEnu command  (Section IV.2)
  1812.             it is used to determine the attributes in the input box
  1813.                for the $? query command (Section V.4)
  1814.       You can change the attributes used with the ATtribute and
  1815.       MNattribute commands.  Each takes a hex byte either in the form 1A
  1816.       or $1A.  The color values are those which are popped up in CTRLALT
  1817.       PLUS' ^@R or CTRLALT's ^@T table.  The first digit is the
  1818.       background and the second foreground with the following rules
  1819.                            Background              Foreground
  1820.                    0       Black                   Black
  1821.                    1       Blue                    Blue
  1822.                    2       Green                   Green
  1823.                    3       Cyan                    Cyan
  1824.                    4       Red                     Red
  1825.                    5       Magenta                 Magenta
  1826.                    6       Brown                   Brown
  1827.                    7       Grey                    Grey
  1828.  
  1829.  
  1830.     Chapter III: DISPLAY TOOLS                                 Page 34
  1831.  
  1832.  
  1833.  
  1834.  
  1835.                   Documentation for BATUTIL, Version 1.0 
  1836.  
  1837.  
  1838.                    8       Black+Blinking          Dark Grey
  1839.                    9       Blue+Blinking           Light Blue
  1840.                    A       Green+Blinking          Light Green
  1841.                    B       Cyan+Blinking           Light Cyan
  1842.                    C       Red+Blinking            Light Red
  1843.                    D       Magenta+Blinking        Light Magenta
  1844.                    E       Brown+Blinking          Yellow
  1845.                    F       Grey+Blinking           White
  1846.       where "blinking" refers to the foreground and should be used
  1847.       sparingly.  For example, AT=$AF would set the attribute to blinking
  1848.       white on green (ugh!).  For the hex digits a-f, you may use upper
  1849.       or lower case.
  1850.  
  1851.             Two attributes are special: $55 and $66.  $55 tells BATUTIL
  1852.       to use the attributes at the cursor position at the time the string
  1853.       writing begins as the attributes for the entire string.  $66 tells
  1854.       BATUTIL to write without changing any attributes.  These two are
  1855.       the same if the block to be written to has uniform attributes but
  1856.       different if they the attributes change as the block is traversed.
  1857.  
  1858.             CLs clears the screen in the current ATtribute or
  1859.       MNattribute and sets the cursor to the upper left.  Here is an
  1860.       example using the ROw and COlumn commands discussed below:
  1861.             BATUTIL {CL}{AT=4F}{RO=15}{CO=5}{EC Hi! there}
  1862.       which would clear the screen in the default attributes of yellow on
  1863.       blue and then display "Hi! there" in white on red starting at row
  1864.       15, column 5.
  1865.  
  1866.             EOline, short for "End of Line" will erase the current line
  1867.       from the cursor position until the end of the line in the current
  1868.       attributes.  If you use a parameter of + as in
  1869.             BATUTIL {EO +}
  1870.       then the entire line is erased.
  1871.  
  1872.             BATUTIL strips leading and tailing blanks from the string
  1873.       following EC so that {EC   hi   } is the same as {EC hi}.  If you
  1874.       actually want the leading or tailing blanks, you'll need to use $S
  1875.       as in {EC $S hi  $S}.  Note that the blanks between the first/final
  1876.       $S and "hi" are not stripped.
  1877.  
  1878.  
  1879.       III.4 The PRetty command
  1880.             Command: PRetty
  1881.             Parameters: string to display with @<Hex> for attribute change
  1882.  
  1883.  
  1884.     Chapter III: DISPLAY TOOLS                                 Page 35
  1885.  
  1886.  
  1887.  
  1888.  
  1889.                   Documentation for BATUTIL, Version 1.0 
  1890.  
  1891.  
  1892.             With the ECho command, you can display strings in multiple
  1893.       colors but it is rather tedious to have to write:
  1894.             BATUTIL {AT 4F}{EC H}{AT 4E}{EC ello} to display Hello with
  1895.       the H in white on read and the rest in yellow on red.  The PRetty
  1896.       command lets you use the @ sign to signal a color change.  If the @
  1897.       sign is followed by two hex digits (or a $ and two hex digits),
  1898.       then the string following it will be displayed in that color until
  1899.       the next @ sign.  So the above command line could be replace by
  1900.             BATUTIL {PR @4FH@4Eello}
  1901.  
  1902.             Until you specify a new attribute with an @ command, PR will
  1903.       use the attributes set with the AT and MN commands (or their
  1904.       defaults 1E and 07).  Irrespective of what you do with @ commands,
  1905.       when you complete a PR command (i.e. the closing } occurs), the
  1906.       value of AT and MN that were in place before will be in effect, for
  1907.       example
  1908.             BATUTIL {AT 4E}{PR @20 hi$S}{EC there}
  1909.       will display "hi " in black on green (attribute 20) but then
  1910.       "there" in yellow on red (attribute 4E).
  1911.  
  1912.             As for the AT and MN commands, the HEX digits following @ can
  1913.       have a-f upper or lower case and an optional $ after the @ is
  1914.       allowed.
  1915.  
  1916.  
  1917.       III.5 Bigecho
  1918.             Commands: BEcho, BPretty, BIgchar
  1919.             Parameters: for BEcho: String to echo with special meanings
  1920.       for leading or trailing ~ or a trailing ^
  1921.                    for BPretty: String with PRetty @ commands; special
  1922.       meaning to trailing ^
  1923.                    for BIgchar a foreground character and optional second
  1924.       background character.  Each can be a character or a number from 1
  1925.       to 255 (255 has special meaning).
  1926.  
  1927.             BIGECHO is a free program from Ctrlalt Associates available
  1928.       on many bulletin boards.  As its name implies, it echoes large
  1929.       characters to the screen.  One font is 8 characters high and 8 wide
  1930.       and uses the built in CGA character set found in ROM.  There are
  1931.       additional smaller sets based on publicly available EGA fonts.
  1932.       BATUTIL includes a BIgecho command which uses the builtin 8x8 font.
  1933.       That is, messages displayed with it are eight lines (except for
  1934.       letters like j and g, the eighth line is blank) and are eight
  1935.       characters wide which means that up to 10 characters can be
  1936.  
  1937.  
  1938.     Chapter III: DISPLAY TOOLS                                 Page 36
  1939.  
  1940.  
  1941.  
  1942.  
  1943.                   Documentation for BATUTIL, Version 1.0 
  1944.  
  1945.  
  1946.       displayed on a line.
  1947.  
  1948.             The simplest command is BEcho which followed by a string
  1949.       displays that string in the large characters.  The current
  1950.       attribute set with AT (or MN) is used.  Any characters that don't
  1951.       fit on the line will be truncated (this may be fewer than 10
  1952.       characters if you don't start with the cursor in column 1).  At the
  1953.       end of the line a "big carriage return" is issued, i.e. the cursor
  1954.       is moved to the first column of the row below the big characters.
  1955.       As we'll explain below, a leading ~ or trailing ^ or ~ will be
  1956.       suppressed and special actions will take place.
  1957.  
  1958.             Each character is stored as a set of dot patterns with the on
  1959.       dots normally displayed as the "foreground" color and the off dots
  1960.       as the "background color".  Thus the letter R is stored as the dot
  1961.       pattern (1 = on, 0 = off)
  1962.             11111100                            $$$$$$
  1963.             01100110                             $$  $$
  1964.             01100110                             $$  $$
  1965.             01111100        corresponding to     $$$$$
  1966.             01101100                             $$ $$
  1967.             01100110                             $$  $$
  1968.             11100110                            $$$  $$
  1969.       By default, BATUTIL, when BEchoing will replace each off dot by a
  1970.       space (character 32 in the ASCII scheme) and each on dot by the
  1971.       solid block (ASCII 219) so that R becomes
  1972.                                 ██████
  1973.                                  ██  ██
  1974.                                  ██  ██
  1975.                                  █████
  1976.                                  ██ ██
  1977.                                  ██  ██
  1978.                                 ███  ██
  1979.       However, you can replace these two characters by any pair of
  1980.       characters using the BIgchar command.  This command takes one or
  1981.       two parameters.  The first parameter specifies the character used
  1982.       for "on" dots while the second, which is optional, the character
  1983.       for off dots.  If the second parameter is absent, the off character
  1984.       is left unchanged from what it was (or from the default space if
  1985.       you haven't changed it).  The parameters can be either a single
  1986.       ASCII character or a number from 01 to 255.  To distinguish a
  1987.       number less than 10 from the corresponding ASCII character, place a
  1988.       0 in front of the number.  Thus {BI 1} will use "1" for the on
  1989.       character while {BI 01} will use a happy face (ASCII 1).  Hex
  1990.  
  1991.  
  1992.     Chapter III: DISPLAY TOOLS                                 Page 37
  1993.  
  1994.  
  1995.  
  1996.  
  1997.                   Documentation for BATUTIL, Version 1.0 
  1998.  
  1999.  
  2000.       digits if proceeded with a $ are also allowed (e.g. $20 in place of
  2001.       32). For example, to show the pattern
  2002.                                      ╬╬
  2003.                                ╬  ╬╬  ╬
  2004.                                ╬  ╬╬  ╬
  2005.                                ╬     ╬╬
  2006.                                ╬  ╬  ╬╬
  2007.                                ╬  ╬╬  ╬
  2008.                                   ╬╬  ╬
  2009.                                ╬╬╬╬╬╬╬╬
  2010.  
  2011.       you'd want to use {BI 32 ╬} or {BI 32 206} or {BI $20 $CE}.  Use of
  2012.       the on character 255 is special.  It is interpreted to use the
  2013.       character itself for the on character (and space for the off
  2014.       character) so
  2015.             BATUTIL {BI 255}{BE Hi there}
  2016.       would yield
  2017.             HH  HH    ii               t    hhh
  2018.             HH  HH                    tt     hh
  2019.             HH  HH   iii             ttttt   hh hh   eeee   rr rrr   eeee
  2020.             HHHHHH    ii              tt     hhh hh ee  ee   rrr rr ee  ee
  2021.             HH  HH    ii              tt     hh  hh eeeeee   rr  rr eeeeee
  2022.             HH  HH    ii              tt t   hh  hh ee       rr     ee
  2023.             HH  HH   iiii              tt   hhh  hh  eeee   rrrr     eeee
  2024.  
  2025.             Metastring translation takes place for the BEchoed string.
  2026.       You'll use this mainly for $S spaces at the start (although it may
  2027.       be more useful to use the CO command to adjust the column of the
  2028.       cursor).  If you do not want the big CR which is issued by default,
  2029.       end the string with a ^.  The cursor is then left on the initial
  2030.       row in the column where the next large character would have
  2031.       appeared.  Thus
  2032.             BATUTIL {BI 255}{BE B^}{BI 219}{BE at}
  2033.       would yield
  2034.             BBBBBB             █
  2035.              BB  BB           ██
  2036.              BB  BB  ████    █████
  2037.              BBBBB      ██    ██
  2038.              BB  BB  █████    ██
  2039.              BB  BB ██  ██    ██ █
  2040.             BBBBBB   ███ ██    ██
  2041.  
  2042.             If you have an off character other than the default space,
  2043.       BATUTIL assumes that you want the entire line to covered with that
  2044.  
  2045.  
  2046.     Chapter III: DISPLAY TOOLS                                 Page 38
  2047.  
  2048.  
  2049.  
  2050.  
  2051.                   Documentation for BATUTIL, Version 1.0 
  2052.  
  2053.  
  2054.       character except where the foreground appears (try
  2055.             BATUTIL {BI 32 206}{CO 9}{BE Hi there}
  2056.       to see what we mean).  If you don't want this effect, add ~ both
  2057.       before and after the string as in {BE ~Hi there~}.  A ~ at the
  2058.       start of the only will not fill in the space before the string.
  2059.       When a non-space off character is used, a ^ at the end and a ~ at
  2060.       the beginning also suppresses filling in spaces after the string.
  2061.  
  2062.             BPretty is like BEcho with the following changes:
  2063.               - as with Pretty, you can use @ followed by a hex attribute
  2064.       to change colors
  2065.               - Off character fillin as described above for BEcho does
  2066.       not take place so leading and trailing ~ characters have no effect (but
  2067.       are stripped off).
  2068.  
  2069.             You cannot redirect BEcho or BPretty to STDOUT (i.e. {ST +}
  2070.       will be ignored by these commands).
  2071.  
  2072.  
  2073.       III.6 Getting Echo/Pretty Input from a file
  2074.             Commands: FEcho, FPretty
  2075.             Parameters: filename, optional label as second parameter
  2076.  
  2077.             If you have several lines to display, using the ECho or PRetty
  2078.       commands can be a nuisance because of the 127 character limitation
  2079.       on the DOS command line.  You'll have to prepare several BATUTIL
  2080.       lines in your batch file and BATUTIL will have to load several times
  2081.       slowing the display.  To avoid these problems, there are the FEcho
  2082.       and FPretty commands which take input for ECho and PRetty from a
  2083.       file.  Rules for finding the filename (your path is searched) and
  2084.       the use of labels are discussed in Section I.5.
  2085.  
  2086.             Lines are read in from the file and processed as they would
  2087.       be by the ECho or PRetty command with two exceptions:
  2088.             -  leading and trailing blanks are not striped off - that is
  2089.       lines will display as they appear.
  2090.             -  each new line in the file causes a new line on the display
  2091.       except that there is not a new line command issued for the last line
  2092.       displayed (unless it ends in a $_).  In particular, blank lines in
  2093.       the file display as blank lines on the screen.
  2094.  
  2095.             Unless turned off with the $T - command, full metastring
  2096.       translation takes place and @ color changes are done by FPretty.
  2097.  
  2098.  
  2099.  
  2100.     Chapter III: DISPLAY TOOLS                                 Page 39
  2101.  
  2102.  
  2103.  
  2104.  
  2105.                   Documentation for BATUTIL, Version 1.0 
  2106.  
  2107.  
  2108.       III.7 Cursor Position and Hiding the Cursor
  2109.             Commands: ROw, COl, CUrsor
  2110.             Parameter:   RO takes a number from 1 to 25; may begin with +
  2111.                              or -.  A T is also legal; see Section IV.5
  2112.                          CO takes a number from 1 to 80; may begin with +
  2113.                              or -.  A T is also legal; see Section IV.5
  2114.                          CU takes + or -
  2115.  
  2116.             If you want a screen in a batch file to begin with 10 blank
  2117.       lines under DOS, you've got to have 10 lines with
  2118.             echo <char 255>
  2119.       (where <char 255> is the ASCII 255 character) or something similar.
  2120.       BATUTIL allows you to control cursor position.  {ROw n} where n
  2121.       runs from 1 to 25 sends the cursor to row n and similar {COl n} to
  2122.       column n.
  2123.  
  2124.             If just a number is listed after RO or CO, then the
  2125.       coordinates are absolute but if you precede then with a + or -,
  2126.       then the coordinates are relative.  For example
  2127.             BATUTIL {RO 5}{CO 5}{EC hi}{RO -3}{CO +3}{EC there}
  2128.       would print "hi" on row 5, col 5 and then "there" on row 2, column
  2129.       10 (since writing "hi" move the cursor to column 7).
  2130.  
  2131.             BATUTIL will not wrap to the next line with relative
  2132.       coordinates and it will stop at the right or left edge if a
  2133.       relative coordinate shift would take it off the screen.  The same
  2134.       is true of the top.  However, if a relative row shift would take
  2135.       it below the bottom edge, it will scroll the screen.
  2136.  
  2137.             It is often more elegant if the cursor is hidden when you are
  2138.       displaying a message on the screen.  {CUrsor -} will hide the
  2139.       cursor while {CUrsor +} will restore it to normal shape.  When
  2140.       BATUTIL finishes running, the cursor is automatically restored so
  2141.       you'll only need {CU +} if you want the cursor to reappear in the
  2142.       middle of a sequence of commands.  Places where you'd normally want
  2143.       BATUTIL to show a cursor like $Q in a set command, BATUTIL will
  2144.       show a cursor even if {CU -} is in effect so you'll only use {CU +}
  2145.       rarely.
  2146.  
  2147.  
  2148.       III.8 The STdout command
  2149.             Command: STdout
  2150.             Parameter: + or -
  2151.  
  2152.  
  2153.  
  2154.     Chapter III: DISPLAY TOOLS                                 Page 40
  2155.  
  2156.  
  2157.  
  2158.  
  2159.                   Documentation for BATUTIL, Version 1.0 
  2160.  
  2161.  
  2162.             DOS' echo command is sent to standard output while, by
  2163.       default, BATUTIL will write directly to the screen.  If you want EC
  2164.       to go to standard output, use {STdout +}.  To turn off this use
  2165.       {STdout -}.
  2166.  
  2167.             You would use {ST +} (the + is not necessary) if you wanted
  2168.       to redirect the output of the EC command (or of the messages from
  2169.       the SA, LO or KI commands) to a file or to NUL.
  2170.  
  2171.             To make a beep in the middle of a BATUTIL sequence, redirect
  2172.       output to STDOUT and echo a ^G as in
  2173.             BATUTIL {ST}{EC ^G}{ST -}{EC You dummy!!!}
  2174.  
  2175.             If you echo to the screen with ST in effect, color commands have
  2176.       no effect.
  2177.  
  2178.  
  2179.       III.9 Sounds
  2180.             Command: SOund, NSound
  2181.             Parameter: SOund takes a single required number from 1 to 20
  2182.                 and an optional second number
  2183.                        NSound takes a - or an optional +
  2184.  
  2185.             BATUTIL comes with ten brief sounds and ten tunes - the ten
  2186.       tunes were made with PIANOMAN.  Each has a number; the ten sounds:
  2187.             1:ping
  2188.             2:wolf whistle
  2189.             3:random electronic sound (needs a repeat to sound much)
  2190.             4:short buzz
  2191.             5:tweet
  2192.             6:alarm clock ring
  2193.             7:buzzer
  2194.             8:electronic sound 1
  2195.             9:electronic sound 2
  2196.            10:train with Doppler effect
  2197.  
  2198.       while the tunes are fragments from:
  2199.            11:Dance of the Clowns
  2200.            12:Habana from Carmen
  2201.            13:Sailor's Hornpipe
  2202.            14:Mapleleaf Rag
  2203.            15:Land of Hope and Glory (Pomp and Circumstance)
  2204.            16:Porky Pig Theme ("That's All Folks")
  2205.            17:Pop Goes the Weasel
  2206.  
  2207.  
  2208.     Chapter III: DISPLAY TOOLS                                 Page 41
  2209.  
  2210.  
  2211.  
  2212.  
  2213.                   Documentation for BATUTIL, Version 1.0 
  2214.  
  2215.  
  2216.            18:William Tell Overture (Lone Ranger's Theme), part I
  2217.            19:William Tell Overture (Lone Ranger's Theme), part II
  2218.            20:Yellow Rose of Texas
  2219.  
  2220.             You invoke a sound with BATUTIL by using the sound command which
  2221.       takes one or two parameters.  The first parameter must be an integer
  2222.       from 1 to 20 and indicates the sound from the above list.  The second
  2223.       parameter indicates the number of times to repeat the sound; if the
  2224.       second parameter is absent the sound is issued once.  For most sounds
  2225.       you won't want any repeats but for sound 3, you'll want a repeat count
  2226.       of 15 or more and sound 4 will do with a few repeats.  The repeat
  2227.       count must lie between 1 and 60.
  2228.  
  2229.             Thus
  2230.               batutil {so 3 30}
  2231.       will repeat sound 3 thirty times.  The William Tell Overture is broken
  2232.       into two parts, to allow you to take an action in the middle as in
  2233.               batutil {ec CTRLALT Associates}{so 18}{ec $Spresents}{so 19}
  2234.  
  2235.             If you don't want the SOund command issued, you can use the
  2236.       NSound command.  This is intended primarily for use in the options
  2237.       set in the environment as in
  2238.             set @BU={NS}
  2239.       which would be useful if you normally had sounds in your batch files
  2240.       but were working late at night and didn't want to disturb others.  The
  2241.       {NS -} command would turn sound back on even if there is a previous
  2242.       {NS}.
  2243.  
  2244.       *******************************************************************
  2245.                                 IMPORTANT NOTE
  2246.          CTRLALT Associates wishes to warn you that the SO command may
  2247.       change in future versions - the precise sounds for sounds 1-10 may
  2248.       change.
  2249.       *******************************************************************
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.  
  2256.  
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.     Chapter III: DISPLAY TOOLS                                 Page 42
  2263.  
  2264.  
  2265.  
  2266.  
  2267.                              Chapter IV:USER INPUT
  2268.  
  2269.  
  2270.       IV.1 Menu Basics
  2271.             Command: MEnu, NMouse
  2272.             Parameter: for MEnu, list of choices
  2273.  
  2274.             DOS provides very little in the way of user input to batch
  2275.       files - essentially the only way to modify the way a batch file
  2276.       runs from one time to the next is to change the parameters on the
  2277.       command line.  BATUTIL provides a number of alternates which we'll
  2278.       discuss in this chapter: you can pop up a menu from which the user
  2279.       chooses and have the choice returned in the errorlevel, you can have
  2280.       the user hit one of a specified number of keys, you can react to a
  2281.       specified state of the Capslock or Numlock or use a number of other
  2282.       devices.  You can also get an input string or filename from the user
  2283.       and store it in the environment but that command is most naturally
  2284.       described in detail in the next chapter.  (see Sections V.4 and
  2285.       V.5)
  2286.  
  2287.             You can have BATUTIL pop up a menu of choices: you can have
  2288.       up to 16 choices - if you try more, BATUTIL will exit with an
  2289.       errorlevel over 200 set (and an error message if verbose mode is
  2290.       on).  Each choice can be up to 60 characters long (after metastring
  2291.       translation).  If the string is longer, then it is truncated at 60
  2292.       characters.  The syntax is
  2293.             BATUTIL {MEnu choice1 choice2 choice3 ...}
  2294.       Each pair of choices must be separated by a space.  If you want a
  2295.       choice to appear with a space in the middle, use $S and rely on
  2296.       metastring translation to turn those into spaces.  For example
  2297.             BATUTIL {ME choice$S1 choice$S2 choice$S3}
  2298.       would pop up a menu of the form
  2299.                            ╒══════════╕
  2300.                            │ choice 1 │
  2301.                            │ choice 2 │
  2302.                            │ choice 3 │
  2303.                            ╘══════════╛
  2304.  
  2305.             A highlight appear initially on the top choice and the
  2306.       following keys (plus others - see below) work:
  2307.             <Down>,<Tab>,<Spacebar>,<+> move the cursor down
  2308.             <Up>,<Shift-Tab>,<Backspace>,<-> move it up
  2309.             <Home>,<PgUp> go to the first choice
  2310.             <End>,<PgDn> go to the last choice
  2311.             <Esc> exits and sets the errorlevel to 0
  2312.             <Enter> makes the highlighted choice
  2313.       If the user picks the nth choice on the menu, the errorlevel is set
  2314.  
  2315.  
  2316.     Chapter IV:USER INPUT                                      Page 43
  2317.  
  2318.  
  2319.  
  2320.  
  2321.                   Documentation for BATUTIL, Version 1.0 
  2322.  
  2323.  
  2324.       to n.
  2325.  
  2326.             In default mode, BATUTIL will look for a Microsoft compatible
  2327.       mouse and, if found, the mouse will work on the menus: moving the
  2328.       mouse up or down will move the highlighting and either mouse button
  2329.       will choose the highlighted item.  If you don't want the mouse
  2330.       active in the menus, use the {NMouse} command.
  2331.  
  2332.             The bar wraps around from top to bottom or vice versa.  The
  2333.       screen is saved upon menu popup and restored on pop down.  In this
  2334.       version of BATUTIL, you cannot modify the menu colors or the border
  2335.       type.  BATUTIL automatically centers the menu on the screen both
  2336.       from left to right and top to bottom.  You can cannot adjust the
  2337.       position of the menu in this version.
  2338.  
  2339.             BATUTIL gives special treatment to the first capital letter
  2340.       or number in each choice.  That symbol will appear in a special
  2341.       highlight and hitting that key will make that choice.  For example
  2342.             BATUTIL {Copy Erase reName format eXit}
  2343.       will display a menu with five choices.  Hitting upper or lower case
  2344.       C, E, N, X will choose the first, second, third or fifth choice.
  2345.       There is no shortcut choice for "format" since no letter is
  2346.       capitalized.  Only the first capitalized letter in each choice
  2347.       counts so that if "Copy" were replaced by "COPY" only the first C
  2348.       would have a unique color and would be the quick key to make that
  2349.       choice.  If two different choices have the same capitalized letter,
  2350.       e.g. if "eXit" above were replaced by "Exit", only the first E
  2351.       would have the special color and only the first choice would be
  2352.       made if an <E> were hit.
  2353.  
  2354.             Future versions of BATUTIL may adopt the Windows standard use
  2355.       of & in menu choices so you should avoid the use of the & symbol in
  2356.       your menu choices (although && for & will be supported).
  2357.  
  2358.             Extra options for how menus look and/or choices are made can
  2359.       be found in the third section.  The sample batch file MENUDEMO.BAT
  2360.       will display sample menus and studying it should help clarify
  2361.       issues of syntax.
  2362.  
  2363.  
  2364.       IV.2 Getting a menu from a file
  2365.             Command: FMenu
  2366.             Parameters: filename, optional label as a second parameter
  2367.  
  2368.  
  2369.  
  2370.     Chapter IV:USER INPUT                                      Page 44
  2371.  
  2372.  
  2373.  
  2374.  
  2375.                   Documentation for BATUTIL, Version 1.0 
  2376.  
  2377.  
  2378.             If your menu has many choices or long descriptions, you will
  2379.       have trouble fitting it on a single DOS command line.  While
  2380.       suitable use of environmental variables and the $x command can get
  2381.       around that, a special command is provided for reading in a menu
  2382.       from a file.  The syntax of the FMenu command is the same as for
  2383.       FEcho and FPretty and is discussed in sections I.5 and III.5.
  2384.  
  2385.             Leading and trailing spaces will be stripped and blank lines
  2386.       will be ignored.  The separate lines will then be viewed as
  2387.       separate lines in the constructed menus.  Embedded blanks will be
  2388.       treated as blanks, that is, unlike the MEnu command where blanks
  2389.       must be indicated with the $S command, blanks in FMenu do not
  2390.       require $S (although metastring translation is done so that $S will
  2391.       be interpreted as spaces).
  2392.  
  2393.             If you are reading in a menu from a file, you have the option of
  2394.       associating each menu item with a line of "help text".  After listing
  2395.       the menu items, place a line with an @ as the first nonblank
  2396.       character.  The rest of that line is ignored, but subsequent lines
  2397.       until the next : line will be regarded as help text.  They are
  2398.       associated in order, in a one-one way with menu choices.  If there are
  2399.       fewer help lines then menu lines, the final few menu items won't have
  2400.       help text.  If there are more help lines than menu items the last few
  2401.       help lines will be ignored.  Help text is displayed in the
  2402.       attributes set with the ATtr or MAttr commands and replaced with
  2403.       blanks in that attribute when the menu finishes.
  2404.  
  2405.  
  2406.       IV.3 Menu Options
  2407.             Commands: MHeader, POp, SHadow, FKey
  2408.             Parameters: MHeader takes a text string
  2409.                         POp takes a + or S to turn on sound effects.
  2410.  
  2411.             There are a number of options you can choose which effect the
  2412.       appearance of menus popped up with the MEnu command and one of them
  2413.       effects which keys work.  If you wish you may add two extra lines
  2414.       to the top of the menu with the MHeader command.  The first line is
  2415.       a text string that you insert as a parameter to MH - spaces are
  2416.       allowed. The second is a graphic line.  The MH command must proceed
  2417.       the ME command.  So
  2418.             BATUTIL {MH This is a header}{ME a b c d e}
  2419.       would display a menu in the form
  2420.                            ╒══════════════════╕
  2421.                            │ This is a header │
  2422.  
  2423.  
  2424.     Chapter IV:USER INPUT                                      Page 45
  2425.  
  2426.  
  2427.  
  2428.  
  2429.                   Documentation for BATUTIL, Version 1.0 
  2430.  
  2431.  
  2432.                            ├──────────────────┤
  2433.                            │ a                │
  2434.                            │ b                │
  2435.                            │ c                │
  2436.                            │ d                │
  2437.                            │ e                │
  2438.                            ╘══════════════════╛
  2439.       The menu choices are always left justified while the header is
  2440.       centered.  You can use $S's to adjust this justification if you
  2441.       wish.  A blank MH, i.e. {MH} will get ignored but {MH $S} would
  2442.       display a blank header.  Like menu choices, headers are truncated
  2443.       at 60 characters if they are longer than that after metastring
  2444.       translation.
  2445.  
  2446.             You can have the menu popup with a shadow effect by using the
  2447.       SHadow command.  The attributes of the shadow are the ones current
  2448.       set with the AT or MN commands.  A typical menu popup command might
  2449.       be set with
  2450.             BATUTIL {AT 30}{CL}{SH}{AT 0}{ME choices.....}
  2451.       The first AT sets the attributes to black on cyan to produce a cyan
  2452.       screen when you CLear the screen.  The second AT then sets the
  2453.       attributes used by the shadow (black).
  2454.  
  2455.             You can have the menu visually explode when popping up and
  2456.       implode upon exiting.  You turn this effect on with the POp
  2457.       command.  POp will take an optional parameter of + or S to also
  2458.       turn on sound effects.  Try out MENUDEMO.BAT to see what the effect
  2459.       is.
  2460.  
  2461.             The final option is to turn on function keys with the FKey
  2462.       command so that
  2463.             BATUTIL {FK}{ME choice1 choice2 choice3}
  2464.       will display a menu
  2465.                            ╒═════════════╕
  2466.                            │F1 - choice1 │
  2467.                            │F2 - choice2 │
  2468.                            │F3 - choice3 │
  2469.                            ╘═════════════╛
  2470.       with Fn labels indicated.  Now in addition to the other choices,
  2471.       the function keys will make choices as will the number keys.  FK
  2472.       will have an effect if your menu has nine or fewer choices.  It is
  2473.       ignored if the menu has more choices than that.
  2474.  
  2475.  
  2476.  
  2477.  
  2478.     Chapter IV:USER INPUT                                      Page 46
  2479.  
  2480.  
  2481.  
  2482.  
  2483.                   Documentation for BATUTIL, Version 1.0 
  2484.  
  2485.  
  2486.             In the unlikely event that you try to put more than one ME
  2487.       command on a line, the options are all reset by the first menu
  2488.       displayed so that, for example
  2489.             BATUTIL {MH hi!}{FK}{ME a b c d}{ME 1 2 3 4}
  2490.       would display a header and function keys on the first menu but not
  2491.       the second.
  2492.  
  2493.  
  2494.       IV.4 GEtkey Basics
  2495.             Command: GEtkey
  2496.             Parameters: list of "keys" separated by spaces, commas or
  2497.                                semicolons.
  2498.  
  2499.             For many purposes where you want single key input, the MEnu
  2500.       command will be best but that is certainly overkill when you really
  2501.       want to ask something like
  2502.             Backup text files (Y/N)?
  2503.       where a simple <y> or <n> will suffice.  The GEtkey command is
  2504.       intended for these situations.  In its simplest form, the GEtkey
  2505.       command is followed by a set of "keys" separated by one of space,
  2506.       comma or semicolon (mixed choices are allowed) in the form:
  2507.             BATUTIL [GEtkey key1 key2 ....]
  2508.       where the syntax for allowed keys will be discussed below.  BATUTIL
  2509.       will then wait patiently for the user to hit one of the keys in the
  2510.       list and then exit with the errorlevel set to n if choice n was
  2511.       made.  For example
  2512.             BATUTIL [GEtkey y n]
  2513.       would wait patiently for one of y,Y,n,N and set the errorlevel to 1
  2514.       if y or Y was picked and 2 if n or N were picked.
  2515.  
  2516.             By default, the keys are not case sensitive so that as above
  2517.       y or Y will work.  Also, by default, BATUTIL will flush the
  2518.       keyboard buffer before getting a keystroke.  BATUTIL will also echo
  2519.       the choice made to give the user feedback and by default will
  2520.       display nothing in response to a key not corresponding to any
  2521.       choice.  However, these defaults, including whether there is any
  2522.       visible echo, can be changed as we'll explain in the next section.
  2523.       The maximum number of keys that can be listed is 40.
  2524.  
  2525.             BATUTIL doesn't mind if a key is repeated in the list of keys
  2526.       but it will report the first match so that
  2527.             BATUTIL [GE Y Y y n n y y n]
  2528.       would return errorlevel 1 with a y or Y and errorlevel 4 with an n
  2529.       or N.
  2530.  
  2531.  
  2532.     Chapter IV:USER INPUT                                      Page 47
  2533.  
  2534.  
  2535.  
  2536.  
  2537.                   Documentation for BATUTIL, Version 1.0 
  2538.  
  2539.  
  2540.             Unlike STACKEY, BATUTIL does not distinguish between the Grey
  2541.       plus and the top row plus nor between the top row numbers and the
  2542.       number pad numbers.
  2543.  
  2544.             Here are the possible choices for keyn in the basic syntax
  2545.       (the two letter codes are essentially those recognized by STACKEY
  2546.       with exceptions like G+ as described above, and the fact that this
  2547.       version does not support keys special to the enhanced keyboard.)
  2548.  
  2549.               -  any single ASCII character with some exceptions given
  2550.                       below
  2551.               -  # followed by any number from 0 to 255 indicating
  2552.                       precisely that ASCII code (there must be no spaces
  2553.                       between the # and the number)
  2554.               -  F1,..,F0; S1,..,S0; A1,..,A0; C1,..,C0 for the 40
  2555.                       function keys as in STACKEY
  2556.               -  ^ followed by any upper or lower case letter for the
  2557.                       control-character, e.g. ^B for <Ctrl-B>
  2558.               -  ^ followed by one of [ \ ] ^ _ for those special ASCII
  2559.                       codes, e.g. ^[ for <Esc>
  2560.               -  ^1, ^3, ^4, ^6, ^7, ^9 for <Ctrl-End>...<Ctrl-PgUp> as
  2561.                       in STACKEY
  2562.               -  @ followed by an alphabetic letter, number, -, _, + or =
  2563.                       indicated the Alt-combination as in STACKEY, e.g.
  2564.                       @A for <Alt-A>
  2565.               -  The following two letter codes which have the same
  2566.                       meaning as in STACKEY: FF, ST, SP, SQ, CB, CR, LA,
  2567.                       RA, UA, DA, TA, ES, TB, BT, BS, LF, DQ, IN, DE, HM,
  2568.                       EN, PU, PD; for example ES for <esc>.
  2569.  
  2570.             The following ASCII codes cannot be used as a single code
  2571.       because they have special meaning to DOS or to BATUTIL:
  2572.  
  2573.             ASCII code (symbol in paren)   │     Use instead
  2574.       ─────────────────────────────────────┼─────────────────────
  2575.              #13 (carriage return)         │   #13, CR, ^M
  2576.              #10 (line feed)               │   #10, LF, ^J
  2577.              >                             │   #62
  2578.              <                             │   #60
  2579.              |                             │   #124
  2580.              %                             │   #37
  2581.              #26 (control Z)               │   #26, ^Z
  2582.               {                            │   #123
  2583.               }                            │   #125
  2584.  
  2585.  
  2586.     Chapter IV:USER INPUT                                      Page 48
  2587.  
  2588.  
  2589.  
  2590.  
  2591.                   Documentation for BATUTIL, Version 1.0 
  2592.  
  2593.  
  2594.               [                            │   #81
  2595.               ]                            │   #83
  2596.               ,                            │   #44
  2597.              <space>                       │   #32, SP
  2598.               ;                            │   #59
  2599.  
  2600.  
  2601.       IV.5 GEtkey Options
  2602.             Commands: NFlush, CSent, VIsual
  2603.             Parameters: For VI - A,1,N,D,DA,D1,DN
  2604.             Extra GEtkey parameters: in first place WAitnn for wait
  2605.                            in first place WAitEnn for wait with Echo
  2606.                            in last place BEep or ELse
  2607.  
  2608.             GEtkey has various extra options to make it more flexible.
  2609.       While it is normally case insensitive, by preceding it with CSent,
  2610.       it will become case sensitive.  For example
  2611.             BATUTIL {CS}{GE Y N}
  2612.       would only accept Y and N and not y or n.
  2613.  
  2614.             Similarly, NFlush will avoid the default behavior which is to
  2615.       flush the keyboard before getting a keystroke.
  2616.  
  2617.             You can adjust the visible feedback that GEtkey gives with the
  2618.       VIsual command.   This command takes a parameter which tells it what
  2619.       to do.  The choices are the following:
  2620.             The default which echoes the choice the user makes as written
  2621.                in the GEtkey command line, e.g. if you use
  2622.                  BATUTIL {GE Y #78}
  2623.                (N is ASCII 78) and the user picks N, then "#78" is echoed
  2624.             1 which will only echo 1 character choices, e.g. with the
  2625.                above example, Y would get echoed but not #78
  2626.             N which suppresses the visual echo (N for No)
  2627.             A which provides an echo for all user responses: if
  2628.                the choice is not one on the list a character plus a
  2629.                ? appears.  For alphanumeric characters, the
  2630.                character itself is used.  For all other keys
  2631.                an upside down question mark appears as the first
  2632.                character.  The incorrect choice indicator is
  2633.                erased each time a new choice is made.
  2634.  
  2635.             By default, BATUTIL inserts a space before echoing a response
  2636.       so that a Y response to
  2637.             BATUTIL {ec Are you sure(Y/N)?}{GE Y N}
  2638.  
  2639.  
  2640.     Chapter IV:USER INPUT                                      Page 49
  2641.  
  2642.  
  2643.  
  2644.  
  2645.                   Documentation for BATUTIL, Version 1.0 
  2646.  
  2647.  
  2648.       would appear on the screen as:
  2649.             Are you sure(Y/N)? Y
  2650.       with a space after the question mark.  If you Don't want this space
  2651.       use a D in the visual command.  You can combine the D parameter with
  2652.       another one so long as you place the D first and place no space
  2653.       after it.  Thus
  2654.             BATUTIL {vi da}{ge Y N}
  2655.       would provide an echo to all choices with no leading space.
  2656.  
  2657.             In addition, the GEtkey command itself has extra options for
  2658.       parameters other than a list of keys.  The last "key" in the list
  2659.       can be one of the key words BEep or ELse (as usual, two letter
  2660.       truncations are allowed).  If the keyword BEep occurs, then the
  2661.       user is beeped for every wrong key picked.  PLEASE use this
  2662.       sparingly.  We hate programs that beep too much and offer it with
  2663.       some misgivings.  Be careful since
  2664.             BATUTIL {GE BE}
  2665.       will do a pretty good imitation of a machine that has crashed
  2666.       (^@<F9> will get you out if CTRLALT PLUS is installed).
  2667.  
  2668.             If the keyword ELse occurs as the last "key", then rather than
  2669.       wait patiently for a key on the list to be hit, BATUTIL will exit
  2670.       with any key hit.  If the key is not on the list then the
  2671.       errorlevel is set to the position of the word "else"; for example
  2672.             BATUTIL {GE y n else}
  2673.       would return errorlevel 1 if y or Y is hit, 2 if n or N is hit and
  2674.       3 for any other key.  If ELse is used a VIsual level of A is ignored.
  2675.  
  2676.             The final option concerns the first "key" on the list which
  2677.       can be WAit followed without any spaces by a number, N, from 1 up
  2678.       to over 8,000 (you will not get an error over 8000 but the response
  2679.       will not be what you expect) or followed by the letter E and a
  2680.       number.  BATUTIL will then not wait patiently for a key to be struck
  2681.       but after approximately N seconds, it will exit with an errorlevel
  2682.       of 0 if no other choice is made.  Thus two lines in a batch file
  2683.       like
  2684.             BATUTIL {GE WA3 y n}
  2685.             if errorlevel 2 goto No
  2686.       would have the effect of choosing a default choice of Y if no key
  2687.       is struck for 3 seconds.  The letter E between the number and WAit
  2688.       tells BATUTIL to echo the first choice on the list if the exit is
  2689.       due to a timeout.  This is for use in examples like the above where
  2690.       the timeout choice will pick a default.  To get the visual feedback
  2691.       for timeout in the above you'd use {GE WAE3 y n}.
  2692.  
  2693.  
  2694.     Chapter IV:USER INPUT                                      Page 50
  2695.  
  2696.  
  2697.  
  2698.  
  2699.                   Documentation for BATUTIL, Version 1.0 
  2700.  
  2701.  
  2702.             There is a system dependent end effect involving the time to
  2703.       load BATUTIL so that WA1 is likely to be anywhere between 1/2 and 2
  2704.       seconds and WA10 will be between 8 and 12 seconds.  In addition, if
  2705.       you start with the GEtkey list with a WAit and end with a BEep and
  2706.       the user holds down the wrong key, then the time before (merciful)
  2707.       exit will be longer than you asked for because beeping takes a
  2708.       considerable amount of time and is not included in the count down
  2709.       time.
  2710.  
  2711.             There may be times that you'll want to visually count down
  2712.       the remaining time.  BATUTIL stores two internal parameters called
  2713.       the timerow and timecolumn, initially set to zero.  If both numbers
  2714.       have no zero values than a countdown will take place with numbers
  2715.       in the row numbered timerow and beginning in column number
  2716.       timecolumn.  There are two ways to change these two parameters.
  2717.       The ROw and COl commands can take the form
  2718.               {RO Ty}{CO Tx}
  2719.       to change these parameters to the numbers y and x.  y must lie in
  2720.       the range 1 to the screen height and x in the range 1 to the
  2721.       screen width.
  2722.  
  2723.             Secondly, if you use $L (L for Location) in an ECho or PRetty
  2724.       command, nothing is displayed for the $L but timerow and timecolumn
  2725.       are set to the current cursor position so
  2726.             BATUTIL {EC Time left: $L   seconds}{GE WA60}
  2727.       will work the way that you'd expect.  Notice that there are three
  2728.       spaces after the $L - two for the numbers 59,.... which will appear
  2729.       and one for a space before the word.
  2730.  
  2731.             There are two additional parameters that you can use with
  2732.       GEtkey WAit and this display.  They are set with
  2733.             {AT Tmn}
  2734.       where m defaults to 3 and n to 4.  m can be from 0 to 3 (the 0 need
  2735.       not be explicit) and adjusts how much is the time is offset.  To
  2736.       take into account the time to load BATUTIL, GEtkey WAits actually
  2737.       subtracts 3/4 of a second off from the time counted so if you ask
  2738.       to count from 60, the time will start at 59.  The wait is m/4
  2739.       seconds if you set m.  In addition, you can change the number
  2740.       counted with n.  Time is counted down in units of n times 1/4
  2741.       second with n between 1 and 8.  So n=2 is half second and n=8 is 2
  2742.       second pauses.  The countdown is in this unit BUT the number set
  2743.       after {GEtkey WAit} is always interpreted as seconds.
  2744.  
  2745.  
  2746.  
  2747.  
  2748.     Chapter IV:USER INPUT                                      Page 51
  2749.  
  2750.  
  2751.  
  2752.  
  2753.                   Documentation for BATUTIL, Version 1.0 
  2754.  
  2755.  
  2756.       IV.6 AScii, SCanread
  2757.             Commands: AScii, SCanread
  2758.             Every keystroke returns a "scan code" and an ASCII code -
  2759.       these are the int 16 codes as discussed in section VI.1 of the
  2760.       STACKEY documentation.  The commands {SC} and {AS} wait for the
  2761.       next key to be pressed and return respectively the scan code or ASCII
  2762.       part.  They are sensitive to the prior use of NFlush.  That is, by
  2763.       default, the keyboard buffer is flushed before reading but a prior
  2764.       use of {NF} can suppress the buffer flushing.
  2765.  
  2766.             SCan codes are always smaller than 128 but ASCII codes could
  2767.       be above 200.  This command is one of only two commands that can return
  2768.       an errorlevel above 200 without indicating an error (the other one is
  2769.       the RUn command).
  2770.  
  2771.  
  2772.       IV.7 Username/Password checking
  2773.             Command: USername
  2774.             Parameters: sequence of names; first one can be a number of
  2775.                           tries; second can be *
  2776.  
  2777.             You may have a batch file which you want to branch depending
  2778.       on what "username" the user enters.  This is what the USername
  2779.       command is for.  The simplest syntax is
  2780.             BATUTIL {US name1 name2 name3 ....}
  2781.       with names separated by spaces.  The names cannot have more than one
  2782.       word since metastring translation does NOT take place.  BATUTIL will
  2783.       display an edit box preceded by ===> which allows entry of a name up to
  2784.       20 characters.  The usual edit keys work.  After the user presses
  2785.       <Enter>, the string entered is compared with the list of names - if
  2786.       there is a match with the Nth name on the list, an errorlevel of N is
  2787.       returned.  Otherwise an error level of 0 is returned.
  2788.  
  2789.             As an option, the first parameter can be a number.  In that
  2790.       case, that number indicates an additional number of tries which are
  2791.       allowed.  If N is 3 or more, and the first entry isn't a match,
  2792.       BATUTIL will beep and display the message:
  2793.             Please try again  ===>
  2794.       When there is only one try left, (and in particular if N=2 after
  2795.       the first try), the message
  2796.             Only one more try ===>
  2797.       will appear.
  2798.  
  2799.  
  2800.  
  2801.  
  2802.     Chapter IV:USER INPUT                                      Page 52
  2803.  
  2804.  
  2805.  
  2806.  
  2807.                   Documentation for BATUTIL, Version 1.0 
  2808.  
  2809.  
  2810.             There is another special and VERY DANGEROUS option to be used
  2811.       with care.  If the first parameter is a number and the second
  2812.       parameter is a * as in
  2813.             BATUTIL {1 * abc def}
  2814.       then if the number of chances is exhausted, rather than return an
  2815.       error level of 0, BATUTIL will respond
  2816.             Invalid!  System halted
  2817.       and go into a tight loop.  This is a very crude security measure
  2818.       since even if you place it in your autoexec.bat, booting from a
  2819.       floppy can give an intruder access to your system.  But it will be
  2820.       effective against an unsophisticated but nosy intruder.
  2821.  
  2822.             When either the number or number and * options are used, the
  2823.       numbering of choices is counted starting after these optional special
  2824.       parameters.  That is, in the last example, "abc" would set an errorlevel
  2825.       of 1 and "def" an errorlevel of 2.
  2826.  
  2827.             By default, USername is not case sensitive and flushes the
  2828.       buffer before asking for input but either of these can be changed
  2829.       by a prior use of {CS} or {NF} as described in section IV.4.
  2830.  
  2831.  
  2832.       IV.8 Parameter Matching
  2833.             Command: PMatch
  2834.             Parameters: list of words
  2835.  
  2836.             The PMatch command is followed by a list of words as in
  2837.             BATUTIL {PM word0 word1 ....}
  2838.       It checks word0 against each of word1, ....  If there is a match
  2839.       first with wordN the error level is set to N, otherwise to 0.  This
  2840.       is typically used to check for errors in batch file parameters.  For
  2841.       example if allowed parameters are "comp" and "bold", you could use
  2842.             echo off
  2843.             batutil {PM %1 comp bold}
  2844.             if errorlevel 1 goto %1
  2845.             echo %1 is not a valid choice; use COMP or BOLD
  2846.             goto end
  2847.             :comp
  2848.             LINES for comp
  2849.             goto end
  2850.             :bold
  2851.             LINES for bold
  2852.             :end
  2853.       This has several advantages over the more usual sequence of
  2854.  
  2855.  
  2856.     Chapter IV:USER INPUT                                      Page 53
  2857.  
  2858.  
  2859.  
  2860.  
  2861.                   Documentation for BATUTIL, Version 1.0 
  2862.  
  2863.  
  2864.             if %1 == bold goto bold
  2865.       First, it is only one command.  Secondly, because labels are not
  2866.       case sensitive, you can use "goto %1" to handle all the different,
  2867.       Bold, BOLD, etc cases.
  2868.  
  2869.             By default, PM is not case sensitive but you can make it so
  2870.       with the {CS} command if you wish.
  2871.  
  2872.  
  2873.       IV.9 Querying the Lock status
  2874.             Command: QLock
  2875.             Parameter: first is C, S, N or I; second (optional) is + or -
  2876.  
  2877.             If you have a long autoexec.bat file which branches in the
  2878.       middle, you may want to set it up with a Y/N question which uses
  2879.       GEtkey with the WA parameter to pick a default choice.  But suppose
  2880.       you don't want the default choice.  Is there any way to overrule
  2881.       the default without waiting around for the Y/N question to appear?
  2882.       The QLock command is precisely made for such situations.  It will
  2883.       read the status of CapsLock or NumLock or .... and return it in the
  2884.       errorlevel.  So you could test for the CapsLock as an antidote to
  2885.       the automatic yes.  We'll describe an example of this in Section
  2886.       VI.3.
  2887.  
  2888.             QLock takes one mandatory parameter and one optional one.
  2889.       The mandatory one determines which lock will get queried; the
  2890.       choices are C, S, N and I for CapsLock, ScrollLock, NumLock and
  2891.       Insert.  Thus
  2892.             BATUTIL [QL C]
  2893.       will test the state of CapsLock and set the errorlevel to 1 if it
  2894.       is on and 0 if it is off.
  2895.  
  2896.             The optional parameter is a + (resp -) which makes sure that
  2897.       the lock state is left on (resp off) when BATUTIL is done.  For
  2898.       example
  2899.             BATUTIL [QL C -]
  2900.       would read the lock state but make sure that it was off when the
  2901.       process was done.
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.     Chapter IV:USER INPUT                                      Page 54
  2911.  
  2912.  
  2913.  
  2914.  
  2915.                         Chapter V:ENVIRONMENTAL CONTROL
  2916.  
  2917.       V.1 Environmental Impact Statement
  2918.  
  2919.             DOS keeps an area of memory called the active environment
  2920.       where it stores the information that you put in your PROMPT and
  2921.       PATH commands and where it stores the location of the file
  2922.       command.com.  In addition, some programs ask you to store
  2923.       information there which you place with the SET command.  Because
  2924.       the DOS command line is limited to 127 characters, you are unable
  2925.       with DOS tools to have a prompt string over 120 characters (127
  2926.       minus the length of "prompt=") nor a path over 122 characters.  The
  2927.       syntax of the set command is
  2928.             set foo=string
  2929.       and we will refer to "foo" as the variable name and "string" as the
  2930.       value of foo.
  2931.  
  2932.             Programs, when they load, are given a copy of this active
  2933.       environment and it is this copy that they are supposed to consult
  2934.       or modify.  The location of the active environment is undocumented
  2935.       and programs are not "supposed" to access it.
  2936.  
  2937.             Batch files can access the environment - if the string
  2938.                  %foo%
  2939.       appears anywhere in a batch file, DOS looks for a variable "foo" in
  2940.       the active environment and if it finds it, then %foo% is replaced by
  2941.       this string.  If there is not a variable named foo, then %foo% is
  2942.       replaced by the empty string.  This %foo%, which only works in
  2943.       batch files, was undocumented until DOS 3.3 but has worked in all
  2944.       versions of DOS.
  2945.  
  2946.             BATUTIL gives you considerable control over the active
  2947.       environment including the following:
  2948.             -  you can query the user and have the answered stored in the
  2949.       environment
  2950.             -  You can have environmental strings up to 255 characters
  2951.       rather than the DOS 127 character limit and, in particular, your
  2952.       PATH can be up to 250 characters and your PROMPT up to 248
  2953.             -  you can add or delete directories from your path.
  2954.             -  you can get a more informative report of what is in your
  2955.       environment than what DOS supplies with the SET command
  2956.             -  you can call up an editor to edit by hand the path or the
  2957.       environment as a whole
  2958.             -  you can save the current environment to a file and later
  2959.       reload it.
  2960.  
  2961.  
  2962.  
  2963.  
  2964.     Chapter V:ENVIRONMENTAL CONTROL..Page 55
  2965.  
  2966.  
  2967.  
  2968.  
  2969.                   Documentation for BATUTIL, Version 1.0 
  2970.  
  2971.  
  2972.             !!!WARNING!!!  BATUTIL can do these things by directly
  2973.       accessing the DOS active environment which violates the general
  2974.       guidelines for "well behaved" programs and uses undocumented
  2975.       features.  We have extensively tested these things with many
  2976.       versions of DOS and we feel that these actions are safe BUT you use
  2977.       these undocumented commands at your own risk.  BATUTIL has certain
  2978.       safeguards built in so that it will exit with an error code if it
  2979.       doesn't find an appropriate candidate for the environment so it
  2980.       should be safe but CTRLALT Associates cannot be responsible for any
  2981.       problems caused by your willingness to use our attempt at giving
  2982.       you improved performance by mildly violating the rules.
  2983.  
  2984.             DOS' treatment of the environment has varied from version to
  2985.       version and while we have tested it under DOS 2.0 thru 4.0, there
  2986.       is a chance that we will not find the proper environment under
  2987.       future versions of DOS.  In addition we have tested running with a
  2988.       path over 122 characters in length and DOS seems to behave
  2989.       perfectly.  However, an application program might get unhappy at
  2990.       finding a path over what it regards as the theoretical maximum.
  2991.       Indeed, Flambeaux Software's TechHelp!! crashes while loading with a
  2992.       path of more than 122 characters and 1986 versions of PKXARC behave
  2993.       erratically with a long path.
  2994.  
  2995.             IMPORTANT NOTES: DOS' SET command only displays the first 128
  2996.       characters in each environmental string.  You may think that
  2997.       BATUTIL has failed to increase your path beyond 128 bytes if you
  2998.       just try set, but the full path will work.  Use BATUTIL {EN} to get
  2999.       a full report of all the strings of any length up to 255 bytes.  If
  3000.       you use another program to get environmental strings over 255 bytes
  3001.       in length, BATUTIL will refuse to load.  If you need strings over
  3002.       255 bytes, let us know and BATUTIL may support them in a future
  3003.       version.
  3004.  
  3005.             Especially with the extra capability that BATUTIL gives you,
  3006.       you may find the 160 character default environment provided by DOS
  3007.       is too small.  You can get around this in two ways:
  3008.             DOS 3.1 has an undocumented option and DOS 3.2/3.3/4.0 a
  3009.       documented option to change the environment with the following command
  3010.       in your CONFIG.SYS:
  3011.             shell=C:\command.com /P /E:xxxx
  3012.       where C:\ can be replaced by whatever path points to command.com
  3013.       and xxxx is the number of bytes you want in the environment under
  3014.       DOS 3.2/3.3/4.0 and it is the number of 16 byte units under DOS 3.1.
  3015.       Thus for a 512 byte environment you'd replace xxxx by 512 under DOS
  3016.  
  3017.  
  3018.     Chapter V:ENVIRONMENTAL CONTROL..Page 56
  3019.  
  3020.  
  3021.  
  3022.  
  3023.                   Documentation for BATUTIL, Version 1.0 
  3024.  
  3025.  
  3026.       3.2/3.3/4.0 and by 32 under DOS 3.1.
  3027.  
  3028.             The second method which you'll need under DOS versions prior
  3029.       to DOS 3.1 is to patch command.com.  Information for such patches
  3030.       is available on many bulletin board systems.
  3031.  
  3032.             SHELLs under DOS 3.2 and later can have enlarged environments.
  3033.       Just use
  3034.             command /e:xxxx
  3035.       where xxxx is the number of bytes that you want environment in the
  3036.       shell of DOS to have.
  3037.  
  3038.             Softlogic's Software Carousel sets up a larger environment in its
  3039.       partitions than you specified in a shell command in your config.sys and
  3040.       since BATUTIL reflects reality, it will report this larger environment
  3041.       size.
  3042.  
  3043.            JP Associates' 4DOS program in certain modes INCLUDING the
  3044.       default for version 2.1 will not work with BATUTIL.  Instead
  3045.       BATUTIL will exit with an error message.  In order for BATUTIL to
  3046.       work with 4DOS you must:
  3047.            -  have version 3.00 or later of 4DOS
  3048.            -  or a version after 2.10 and you load 4DOS with the /M:xxxx
  3049.       (where xxxx is the desired environment size) switch
  3050.             In addition, be warned that there is a special problem that
  3051.       arises if you try to run 4DOS and BATUTIL together on a system
  3052.       whose underlying DOS version is 3.2.  If you load a shell of 4DOS
  3053.       (perhaps as the base command processor) and then load a shell of
  3054.       command.com, BATUTIL will not change the active DOS environment but
  3055.       another memory area.  No harm will be done but you will not effect
  3056.       the path or other DOS variables in this rather special
  3057.       circumstance.
  3058.  
  3059.  
  3060.       V.2 Environment Reports
  3061.             Command: ENvrep
  3062.  
  3063.             The command
  3064.               BATUTIL {ENvrep}
  3065.       will display a listing of all environmental strings as DOS' SET
  3066.       command does but it will also list the following:
  3067.             - the length of each environmental string
  3068.             - the total size and amount of free space in the environment
  3069.             - the location of the active environment
  3070.  
  3071.  
  3072.     Chapter V:ENVIRONMENTAL CONTROL..Page 57
  3073.  
  3074.  
  3075.  
  3076.  
  3077.                   Documentation for BATUTIL, Version 1.0 
  3078.  
  3079.  
  3080.       V.3 SEt basics
  3081.             Command: SEt
  3082.             Parameters: var1=string1 var2=string2 (separated by spaces)
  3083.  
  3084.             BATUTIL has a SEt command that lets you place variables into
  3085.       the environment.  The syntax is
  3086.             BATUTIL {SE foo1=string1 foo2=string2 ...}
  3087.       You can enter more than one string at a time (although one string
  3088.       is also allowed).  Distinct strings are separated by spaces.  If any
  3089.       string is missing an = sign, BATUTIL will exit with an errorlevel of
  3090.       208 (and issues a message if you are in Verbose mode).  If you want
  3091.       to place a space into the value of one of the strings, use $S which
  3092.       will get translated into a space.
  3093.  
  3094.             "But", you say, "DOS' SET lets me put strings in the
  3095.       environment, so why do I need BATUTIL."  Often DOS is the way to go
  3096.       but BATUTIL's set has the following advantages:
  3097.  
  3098.             - You can place more than one variable into the environment
  3099.       at a time
  3100.             - BATUTIL does metastring translation so that you could use
  3101.       something like
  3102.                  BATUTIL {se today=$E}
  3103.       to get today's date in English into the environment or if you want
  3104.       control-Z as part of your prompt string (the right pointing arrow
  3105.       is an interesting alternative to the more usual greater than sign),
  3106.       then you'll have trouble doing that from a batch file but the pair of
  3107.       symbols ^ and Z in a BATUTIL SET will work, e.g.
  3108.                batutil {se prompt=$$p)^Z}
  3109.             - You can use SEt to get variable values of length over 127
  3110.       characters into the environment (see below).
  3111.  
  3112.             As with DOS' set command, {SE foo=} with no string after
  3113.       "foo=" will remove any variable named "foo" from the environment.
  3114.  
  3115.             Because of the metastring translation, you'll need to
  3116.       exercise some care when using prompt strings.  For example, if your
  3117.       prompt were
  3118.             $t$_$p$g
  3119.       which displays the time and then on a second line the path and a
  3120.       '>', and you decided to add the date and used
  3121.             BATUTIL {SE prompt=$d;$X(prompt)}
  3122.       you'd not get what you wanted.  The $d would get translated into
  3123.       today's date (which wouldn't be bad although it would waste
  3124.  
  3125.  
  3126.     Chapter V:ENVIRONMENTAL CONTROL..Page 58
  3127.  
  3128.  
  3129.  
  3130.  
  3131.                   Documentation for BATUTIL, Version 1.0 
  3132.  
  3133.  
  3134.       environment space) but the $t and $p would get "evaluated" and
  3135.       would no longer change as you the time changed or you changed
  3136.       directory.  Instead you should use
  3137.             BATUTIL {SE prompt=$$d;$x(prompt)}
  3138.       (recall that $X does metastring translation while $x does not).
  3139.       Careful use of $x, $$ and occasional use of the {$T - } will avoid
  3140.       problems but care is needed.
  3141.  
  3142.             DOS is limited to 127 characters on a command line and it
  3143.       does %foo% translations at a point where that limitation is still
  3144.       in effect so that if your path has 120 characters and you use the
  3145.       DOS command
  3146.             set path=%path%;C:\bin;
  3147.       in a batch file, DOS will expand the %path% and crowd all but the
  3148.       ";C" off the line.  But BATUTIL only does the translation later and
  3149.       allows environmental strings up to 255 characters so that
  3150.             BATUTIL {se path=$x(path);C:\bin;}
  3151.       would work perfectly - it is with the use of the $x command that
  3152.       you can get environment strings over 127 characters (as well as
  3153.       with the ADdpath and LOadenv) commands.  Actually, you wouldn't
  3154.       want to use the above command line - adding to your path is
  3155.       sufficiently important that it is a primitive BATUTIL command and
  3156.       you'd use:
  3157.             BATUTIL {AD C:\bin}
  3158.  
  3159.  
  3160.       V.4 Getting User Strings into the Environment
  3161.             Commands: ?Length, ?Size, LEngth, QUery
  3162.             Parameters: ?L takes a number from 1 to 255
  3163.                         ?S takes a number from 1 to 80
  3164.                         LE takes a string
  3165.                         QU takes -
  3166.             Metastrings: $Q, $?
  3167.  
  3168.             As part of the set command, you can query the user for a
  3169.       string to be placed into the environment.  The metastrings $Q and
  3170.       $? are used with slightly different display possibilities.  Do not
  3171.       confuse $q (the prompt metastring for the character =) and $Q, the
  3172.       Query command.  The usual form that you'll use is
  3173.             BATUTIL {se foo=$Q}
  3174.       or
  3175.             BATUTIL {se foo=$?}
  3176.       although there is no reason that $Q or $? couldn't be part of a
  3177.       complex string.  Only one $Q or $? will be translated per string so
  3178.  
  3179.  
  3180.     Chapter V:ENVIRONMENTAL CONTROL..Page 59
  3181.  
  3182.  
  3183.  
  3184.  
  3185.                   Documentation for BATUTIL, Version 1.0 
  3186.  
  3187.  
  3188.       that
  3189.             BATUTIL {se foo=$Q$Q$?}
  3190.       would Query the user and append the characters "$Q$?" to the end of
  3191.       the input.  But multiple strings each with its on query are in
  3192.       principle possible so that
  3193.             BATUTIL {se foo1=$Q foo2=$Q}
  3194.       would query the user twice.
  3195.  
  3196.             You will need to place an appropriate prompt on the screen to
  3197.       indicate to the user what you expect as in
  3198.             BATUTIL {EC Enter filename to use$_}{SE foo=$Q}
  3199.       or
  3200.             BATUTIL {EC Enter two filenames to use$_}{SE foo1=$Q foo2=$Q}
  3201.  
  3202.             With the $Q command, the BATUTIL adds it own prompt of
  3203.                 ===>
  3204.       in distinctive colors (yellow on black on a color monitor) and then
  3205.       displays an edit box in reverse video on a monochrome screen and
  3206.       yellow on green on a color monitor.  The edit box is 50 columns
  3207.       wide and the maximum string length that can be entered is 80
  3208.       characters (with horizontal scrolling as described in Section I.7).
  3209.       These can be adjusted with the ?L and ?S commands as we'll
  3210.       describe.  All the editing commands discussed in Section I.7 are
  3211.       active.
  3212.  
  3213.             The $? gives you more control over the display but at the
  3214.       "cost" of more effort on your part.  You can customize your own
  3215.       prompt.  Rather than use a fixed set of attributes, the AT and MN
  3216.       attributes are used to determine the colors of the edit window.
  3217.       For example, to duplicate
  3218.             BATUTIL {SE foo=$Q}
  3219.       you'd use
  3220.             BATUTIL {AT 0E}{EC ===$g$S}{AT 2E}{MN 70}{SE foo=$?}
  3221.       Of course, you would not do this to duplicated $Q but you can adjust
  3222.       colors and prompts in this way.
  3223.  
  3224.             The {$T -} command does NOT turn off $Q/$? expansion.
  3225.       Rather you can turn this off independently of the state of $T with
  3226.       the QUery command: {QU -} would turn it off and {QU +} will turn it
  3227.       back on.
  3228.  
  3229.             While the default maximum length of input for the $Q and $?
  3230.       commands is 80 characters, you can adjust this with the ?L command.
  3231.       Similarly, the ?S command effects the size of the edit window.
  3232.  
  3233.  
  3234.     Chapter V:ENVIRONMENTAL CONTROL..Page 60
  3235.  
  3236.  
  3237.  
  3238.  
  3239.                   Documentation for BATUTIL, Version 1.0 
  3240.  
  3241.  
  3242.       Thus
  3243.             BATUTIL {?L 30}{?S 5}{set foo=$Q}
  3244.       would give a small 5 character window scrolling to support a 30
  3245.       character input.
  3246.  
  3247.             The ?S command takes a value between 1 and 80 - any other
  3248.       value will cause BATUTIL to exit with a syntax error.  With window
  3249.       sizes that are close to maximum value (or if you have moved the
  3250.       cursor prior to calling {SE foo=$?}), the edit window may wrap to
  3251.       the next line.  ?L will take values from 1 to 255.  If ?L is
  3252.       smaller than ?S then BATUTIL automatically adjust ?S down to the
  3253.       size of ?L.
  3254.  
  3255.             If you want to know the length of a string input by the user
  3256.       or which you'll need for some other reason [LEngth string] will
  3257.       return that length after metastring translation unless {$T -} is in
  3258.       effect.  An error level of 199 is returned if the string is 199
  3259.       characters or more in length.  Normally, LE is used with something
  3260.       requiring metastring translation, especially a $x variable.
  3261.  
  3262.  
  3263.       V.5 Using the file pick list
  3264.             Metastrings: $F,$f
  3265.  
  3266.             BATUTIL lets you popup a file list from which the user can choose
  3267.       a file and you can have the filename chosen saved in the
  3268.       environment.  Within the set command, just use a $f or $F on the
  3269.       right side of an equal sign and a file list will popup.  The list
  3270.       will have the statement
  3271.              <F1> for Help
  3272.       and hitting <F1> will give information on what is available:
  3273.             Arrows move the bar cursor by one space
  3274.             <PgUp> <PgDn> move up/down by one panel of 21 files
  3275.             <Home> <End>  move to the first/last file
  3276.       The list begins with a listing of subdirectories.  Hitting enter on the
  3277.       subdirectory will cause that subdirectory to be displayed.  Included in
  3278.       the list unless you are already in the root are, two special ones
  3279.       labelled <PARENT_DIR> and <ROOT_DIR> which go to the obvious
  3280.       places; in addition hitting
  3281.             . will go to the parent directory
  3282.             \ will go to the root directory
  3283.             a letter (e.g. a or A) will change drives
  3284.             <space> will go to the initial directory
  3285.             <tab> will go to the default directory (see below)
  3286.  
  3287.  
  3288.     Chapter V:ENVIRONMENTAL CONTROL..Page 61
  3289.  
  3290.  
  3291.  
  3292.  
  3293.                   Documentation for BATUTIL, Version 1.0 
  3294.  
  3295.  
  3296.             alt-letter will move to the first file beginning with that
  3297.       letter
  3298.             <Enter> chooses that file and fills its full pathname in
  3299.       place of the $f.  The directory is stored in the variable FDIR with
  3300.       the provisos discussed in section II.6.  <Esc> exits with $f and
  3301.       FDIR replaced by the empty string.  If the user exits with <Enter>,
  3302.       RC is set to 0 and if with <Esc> to 2.  If there is a DOS disk
  3303.       error, RC is set to the 23x errorcodes normally placed in the
  3304.       errorlevel.  If a path is specified but the path is invalid, RC is
  3305.       set to 1.
  3306.  
  3307.             Optionally, you can place a filespec in parentheses immediately
  3308.       after $f as in
  3309.             $f(A:d*.*)
  3310.       The filelist will then only list matching files and subdirectories. If
  3311.       there are no matching files or subdirectories, then BATUTIL exits
  3312.       with RC set to 3.  If no wildcards are given and there is a single
  3313.       matching file then the single file is used in place of $f and RC is
  3314.       set to 1.
  3315.  
  3316.             Metastring processing is done inside $f primarily to allow for
  3317.       the use of $x.  Thus the following works as you'd expect:
  3318.             batutil {ec Enter filespec}{set foo=$Q foo=$f($x(foo))}
  3319.  
  3320.             Only the first $f is expanded on the right side of an equal sign.
  3321.       However, within a single set command, $f's associated with distinct
  3322.       variables will each be processed.  While this capability is there,
  3323.       we recommend against normally using it as the user can get confused
  3324.       about there really being several commands.
  3325.  
  3326.  
  3327.       V.6 Saving and loading the environment to a file
  3328.             Commands: SAvenv, LOadenv, KIllenv
  3329.             Parameters: SAvenv and LOadenv take a filename with LOad allowing
  3330.                  an extra /m to merge; KIllenv takes a list of variables
  3331.                  to keep.
  3332.  
  3333.  
  3334.             BATUTIL allows you to do automated bulk operations to the
  3335.       environment:
  3336.  
  3337.             - {SAvenv filename} will save a copy of the environment in the
  3338.       file "filename".  If the file already exists, you will asked
  3339.       confirmation to overwrite.  If the user responds N, then the error
  3340.  
  3341.  
  3342.     Chapter V:ENVIRONMENTAL CONTROL..Page 62
  3343.  
  3344.  
  3345.  
  3346.  
  3347.                   Documentation for BATUTIL, Version 1.0 
  3348.  
  3349.  
  3350.       level is set to 199
  3351.  
  3352.             -  {LOadenv filename} and {LOad filename /m} will load a
  3353.       previously saved environment.  The first command will completely
  3354.       replace the environment with the one in the file saving nothing
  3355.       from the prior environment.  The command with the /m will merge the
  3356.       saved environment with the current environment - variables which
  3357.       are in the current environment but not in the saved environment
  3358.       will be kept.  Variables which occur in both the current and saved
  3359.       environment will be assigned the value in the filename.
  3360.  
  3361.             - {KIllenv} will remove all strings from the current
  3362.       environment except for the COMSPEC string which BATUTIL will not
  3363.       remove (if you insist on removing it, use
  3364.             SET comspec=
  3365.       as a DOS command).  In addition you can save some specific
  3366.       environmental variables by including their names as parameters.
  3367.       For example
  3368.             BATUTIL {KI path prompt}
  3369.       would remove all non-DOS variables from the environment.
  3370.  
  3371.             The environment saved by the {SA} command is saved as an
  3372.       ASCII file with one variable per line.  You can edit it with any
  3373.       ASCII editor that will support lines which are long enough.  You
  3374.       can freely add lines but no line should have over 255 characters.
  3375.       Any line added must have the form
  3376.             VARNAME=value
  3377.       (without leading blanks) where VARNAME is all caps, and value is
  3378.       not an empty string.
  3379.  
  3380.             The KIllenv command is intended for use in third party batch
  3381.       files if used with care.  You can save the user's environment to a
  3382.       file, use KIllenv and later load the saved environment.  You can
  3383.       then use the environment for variable space while your batch file
  3384.       runs.  It is recommended that if you do this, you exercise several
  3385.       cautions:
  3386.             -  check for sufficient space without killing the environment
  3387.       and if there is sufficient space, don't save and kill.  You could
  3388.       also consider checking if the user has DOS 3.2 or later and get the
  3389.       larger environment by using command /c /e:1024 to rerun the batch
  3390.       file with a larger environment
  3391.             -  warn the user what you are about to do and give them the
  3392.       option of aborting the batch file.
  3393.             -  Be sure to use SA and KI in the same command line as in
  3394.  
  3395.  
  3396.     Chapter V:ENVIRONMENTAL CONTROL..Page 63
  3397.  
  3398.  
  3399.  
  3400.  
  3401.                   Documentation for BATUTIL, Version 1.0 
  3402.  
  3403.  
  3404.                   BATUTIL {SA foo1}{KI}
  3405.       since a file error during the save operation will halt BATUTIL and
  3406.       so the KI command won't happen if the SA doesn't work.  Also,
  3407.       BATUTIL halts if the file exists and the user says not to
  3408.       overwrite.  Check for errorlevel 199
  3409.             -  Be sure to erase the saved environment file when your
  3410.       batch file ends to avoid giving the user a file he/she knows
  3411.       nothing about and to avoid problems if your batch file is rerun.
  3412.             -  Check for the existence of the filename you want to save
  3413.       for first and give the user more useful information than the
  3414.       general `File exists; Overwrite (Y/N)?' that BATUTIL provides.
  3415.  
  3416.  
  3417.       V.7. Batch file path control
  3418.             Commands: ADdpath, DElpath
  3419.             Parameters: list of paths separated by space, comma or
  3420.       semicolon - $p and $P are processed.
  3421.  
  3422.             BATUTIL will let you easily add additional directories to
  3423.       your DOS search path and delete directories.  The syntax is
  3424.             BATUTIL {AD dir1 dir2 ...}
  3425.             BATUTIL {DE dir1 dir2 ...}
  3426.       The keyword ADdpath or DElpath and the directories in the list may
  3427.       be separated from one another by any combination of spaces,
  3428.       semicolons, and commas.
  3429.  
  3430.             ADdpath can be compared with what you can do in a DOS batch
  3431.       file by saying
  3432.             set path=%path%dir1;dir2;
  3433.       ADdpath allows paths over 127 characters (actually, if you really
  3434.       want a path over 127 characters, you should consider changing your
  3435.       disk setup - too many directory entries in a path will slow DOS
  3436.       down), the $p,$P translation as discussed below and it won't let
  3437.       you duplicate an entry in the path list (so long as you don't try
  3438.       to do something like C:\bin and \bin which it will allow).
  3439.  
  3440.             DElpath will search the path and remove the specified
  3441.       directories if found in the path.  The string listed in the command
  3442.       must agree (except for case) with a directory name in the path.
  3443.  
  3444.             ADdpath and DElpath do not do metastring translation except
  3445.       for $p and $P.  For example, the following batch files would add
  3446.       and subtract the current directory from the DOS path
  3447.  
  3448.  
  3449.  
  3450.     Chapter V:ENVIRONMENTAL CONTROL..Page 64
  3451.  
  3452.  
  3453.  
  3454.  
  3455.                   Documentation for BATUTIL, Version 1.0 
  3456.  
  3457.  
  3458.             addpath.bat
  3459.               BATUTIL {AD $p}
  3460.  
  3461.             delpath.bat
  3462.               BATUTIL {DE $p}
  3463.  
  3464.       A typical application of these commands would be if a program
  3465.       silly.com requires that its directory C:\rudeprog be in the path
  3466.       when it is run.  A batch file to do this would read:
  3467.             BATUTIL {AD C:\rudeprog}
  3468.             C:\rudeprog\silly
  3469.             BATUTIL {DE C:\rudeprog}
  3470.  
  3471.             BATUTIL has no problem reading in paths which don't end with
  3472.       a semicolon but the paths that it writes out always have a
  3473.       semicolon at the end.
  3474.  
  3475.             The AD and DE commands return information in the errorlevel
  3476.       and/or variable RC.  AD tells you the number of directories actually
  3477.       added to the path (since entries are not duplicated, this may be
  3478.       smaller than the number listed) and DE the number deleted (since
  3479.       you may have listed a directory not in the path, this may be
  3480.       smaller the number listed).
  3481.  
  3482.  
  3483.       V.8 Direct Editing of the path
  3484.             Command: PAthedit, NBeep
  3485.             BATUTIL {PAthedit}
  3486.       brings up an interactive editor which allows you to edit your path.
  3487.       Up to 17 directories can be displayed at once, with more, you can
  3488.       use the arrow keys to scroll or PgUp/PgDn to move by 10 directories
  3489.       at a time.  One of the directories is highlighted.  <Up>, <Down>,
  3490.       <Home>, <End> do the obvious thing to the highlight.  <Enter> picks out
  3491.       that entry and lets you edit it using the line editor discussed in
  3492.       section I.5.  Ctrl-D will delete the directory the cursor is on from
  3493.       the path list (but not change the actually on disk directory) and Ctrl-
  3494.       A will let you add a new path.
  3495.  
  3496.             The order of the directories in your path matters somewhat in
  3497.       that DOS searches in the specified order (in particular, if you
  3498.       have a RAM disk, put its directories before the any others).  Alt-T
  3499.       moves the highlighted directory to the Top of the list and Alt-B to
  3500.       the bottom.
  3501.  
  3502.  
  3503.  
  3504.     Chapter V:ENVIRONMENTAL CONTROL..Page 65
  3505.  
  3506.  
  3507.  
  3508.  
  3509.                   Documentation for BATUTIL, Version 1.0 
  3510.  
  3511.  
  3512.             All these changes only effect the in memory copy of the path
  3513.       but not the true path as stored in the environment.  When you press
  3514.       <Esc> to exit, if you have made any changes, then BATUTIL will
  3515.       offer to save them to the true path as stored in the DOS
  3516.       environment.
  3517.  
  3518.             There are various places that BATUTIL will beep and display a
  3519.       message to warn you; for example, when you exit and are asked if
  3520.       you want to save the edited environment.  If you don't like beeps,
  3521.       the NBeep command will turn off the beeps for the PAthedit and
  3522.       EDitenv commands.  You could call up the PAthedit command with
  3523.             BATUTIL {NB}{PA}
  3524.       or can place {NB} in the BATUTIL environment string.
  3525.  
  3526.  
  3527.       V.9 Direct editing of the environment
  3528.             Command: EDitenv
  3529.             Parameter: optional name
  3530.  
  3531.             BATUTIL {EDitenv}
  3532.       brings up an edit module for the full environment very similar to
  3533.       that discussed in the last section.  The main difference are the
  3534.       following:
  3535.             - Total and free environment space is listed on the bottom
  3536.       line
  3537.             - Only the first 80 characters of each environment string is
  3538.       displayed.
  3539.             - Each environmental variable has two pieces: the name of the
  3540.       variable and its value stored as
  3541.                 name=value
  3542.       <Enter> allows you to edit the value while ^<Enter> the name.
  3543.  
  3544.             While Ctrl-T/B are active, the order of variables in the
  3545.       environment does not normally make any difference.
  3546.  
  3547.             You can also follow ED with a single variable name.  If the
  3548.       variable is in the environment, that value is brought into the line
  3549.       editor for editing.  If it is a new variable you get to use the
  3550.       line editor to define it.  NBeep applies to this module also.  You
  3551.       are limited to editing environments with no more than 511 strings
  3552.       (each with no more than 255 bytes).
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.     Chapter V:ENVIRONMENTAL CONTROL..Page 66
  3559.  
  3560.  
  3561.  
  3562.  
  3563.                           Chapter VI:TIPS AND EXAMPLES
  3564.  
  3565.       VI.1 General tips
  3566.  
  3567.             After a BATUTIL menu, you'll typically need to branch on a
  3568.       number of different possibilities.  The commands
  3569.             if errorlevel 6 goto menu6
  3570.             if errorlevel 5 goto menu5
  3571.             if errorlevel 4 goto menu4
  3572.             if errorlevel 3 goto menu3
  3573.             if errorlevel 2 goto menu2
  3574.             if errorlevel 1 goto menu1
  3575.       followed by choice 0 code will work but the following is more
  3576.       elegant.  If there are six menu choices, have labels :menu0,...,
  3577.       :menu6.  Use {ME ..} (or {FM ..}) rather than [ME ..] so the choice
  3578.       is placed in the environmental variable RC and then follow this
  3579.       command with
  3580.             goto menu%RC%
  3581.       This gives you a kind of CASE statement.  For an example of this
  3582.       see the sample batch file BUDEMO.BAT.
  3583.  
  3584.             Because BATUTIL takes time to reload, you'll want to place
  3585.       several commands on one line.  But what if you want to get
  3586.       information about several hardware items - isn't there a problem
  3587.       that each will use the environmental variable rc?  No, because
  3588.       unlike DOS' %rc% which is evaluated before the command line is
  3589.       acted on, BATUTIL's $x(rc) does its translation as the command with
  3590.       $x is reached.  Thus
  3591.             BATUTIL {#D}{set d1=$x(rc)}{@D}
  3592.       would return the total disk space (#D) in the variable d1 and the
  3593.       free disk space (@D) in rc.  For uses of this idea, see the sample
  3594.       batch file equip.bat.
  3595.  
  3596.             It is most convenient to place the fmenu and fecho lines in
  3597.       the batch file itself.  If the batch file is foobar.bat, you could
  3598.       use
  3599.             {fecho foobar.bat label}
  3600.       but that will fail if the user renames the batch file so use
  3601.             {fecho %0 label}
  3602.       instead.  To handle this possibility, BATUTIL looks first for the
  3603.       filename specified with a {fecho ....} command by name and if that
  3604.       fails it tries the extension bat.
  3605.  
  3606.  
  3607.       VI.2 Returning to your initial directory
  3608.  
  3609.  
  3610.  
  3611.  
  3612.     Chapter VI:TIPS AND EXAMPLES                               Page 67
  3613.  
  3614.  
  3615.  
  3616.  
  3617.                   Documentation for BATUTIL, Version 1.0 
  3618.  
  3619.  
  3620.             You can arrange to return to your initial directory in a
  3621.       batch file, say one that changes to C:\123 and runs lotus with
  3622.             batutil {set dr=$n di=$p}
  3623.             C:
  3624.             cd \123
  3625.             lotus
  3626.             %dr%:
  3627.             cd %di%
  3628.       This uses DOS' environmental substitution.
  3629.  
  3630.             You could arrange to save a set of your earlier directories and
  3631.       return to them with two batch files, pushdir and popdir.
  3632.       Pushdir.bat would read
  3633.             batutil {set dr3=$x(dr2) di3=$x(di2) dr2=$x(dr1) di2=$x(di1)
  3634.                           dr1=$n di1=$p}
  3635.       all on one line.  Popdir would read
  3636.             %dr1%
  3637.             cd %dr1%
  3638.             batutil {set dr2=$x(dr3) di2=$x(di3) dr1=$x(dr2) di1=$x(di2)
  3639.                            dr3=  di3= }
  3640.  
  3641.             In terms of directory manipulation, suppose you not only want
  3642.       to return to the original directory but you have a program silly in
  3643.       \foo which insists that its directory be in the path even if it is
  3644.       the default directory.  You want to add it to the path but later
  3645.       remove it.  Use:
  3646.             batutil {set dr=$n di=$p}{ad C:\foo}
  3647.             C:
  3648.             cd \foo
  3649.             silly
  3650.             batutil {de C:\foo)
  3651.             %dr%:
  3652.             cd %di%
  3653.  
  3654.       VI.3 Using BATUTIL in your autoexec.bat
  3655.  
  3656.             There are a number of actions special to an autoexec.bat
  3657.       that make BATUTIL valuable.  Your autoexec.bat may take a long time
  3658.       to run because you run a defragmenting utility like VOPT or use a
  3659.       FAT/root dir saver like Norton's FR or you might copy a lot of
  3660.       files to a RAM disk.  You might care to branch at the end of the
  3661.       batch file, say to run Software Carousel or not.  Of course, you
  3662.       can ask a question but what if you don't want to always stand
  3663.       around and would like to default to running Carousel if you aren't
  3664.  
  3665.  
  3666.     Chapter VI:TIPS AND EXAMPLES                               Page 68
  3667.  
  3668.  
  3669.  
  3670.  
  3671.                   Documentation for BATUTIL, Version 1.0 
  3672.  
  3673.  
  3674.       there.  You could use (as a fragment of your autoexec.bat):
  3675.             BATUTIL {ec Run Carousel (Y/N)?}{ge wa6 y n}
  3676.             if errorlevel 2 goto nocar
  3677.             carousel
  3678.             :nocar
  3679.       You could even have the time counted down by replacing the first
  3680.       line with
  3681.             BATUTIL {ec Run Carousel (Y/N)? $L   secs left}{ge wa6 y n}
  3682.  
  3683.             So you've solved the problem of waiting around if you do want
  3684.       to run Carousel.  But what if you don't want to.  With the above
  3685.       fragment you'd need to wait around.  Here is where the test of the
  3686.       lock keys comes in.  Immediately before the first line of the above
  3687.       fragment, you could put
  3688.             BATUTIL {ql C-}
  3689.             if errorlevel 1 goto nocar
  3690.       Then, if you hit Capslock before you go off Carousel wouldn't run.
  3691.       Actually, you could avoid an extra running of batutil and two
  3692.       lines of the file by using:
  3693.             BATUTIL {ql C-}{HA $x(rc)=1}{ec Run Carousel (Y/N)?}{ge wa6 y n}
  3694.       as the first line of the fragment.  For then if Caps was set, the
  3695.       HAltif command should cause BATUTIL to exit with an errorlevel
  3696.       above 2 (namely with errorlevel 255).
  3697.  
  3698.             Another problem that you'll often want to cope with in a
  3699.       batch file is some operation, like defragmentation that you only
  3700.       want to run once a day.  Here is a fragment to do that:
  3701.             BATUTIL {to newday.tst}
  3702.             if not errorlevel 1 goto already
  3703.             echo a >newday.tst
  3704.             STUFF TO DO ONCE
  3705.             :already
  3706.       What this does, is if the error level is exactly 0, then one skips
  3707.       to the label already.  Otherwise, the file newday.tst is given
  3708.       today's date so that the next time it is run, "BATUTIL {to
  3709.       newday.tst}" will return errorlevel 0.  But what if you sometimes
  3710.       work past midnight and don't want the newday stuff done until
  3711.       morning.  Replace
  3712.             BATUTIL {to newday.tst}
  3713.       with
  3714.             BATUTIL {to 5 newday.tst}
  3715.       which will make the change over at 5AM rather than midnight.
  3716.  
  3717.  
  3718.  
  3719.  
  3720.     Chapter VI:TIPS AND EXAMPLES                               Page 69
  3721.  
  3722.  
  3723.  
  3724.  
  3725.                   Documentation for BATUTIL, Version 1.0 
  3726.  
  3727.  
  3728.       VI.4 A shell for LIST
  3729.  
  3730.             Vern Buerg's LIST program is a lovely file lister but you
  3731.       cannot choose files from a list.  If you call it with wildcards, it
  3732.       will successively display every file in the list and going back and
  3733.       forth through them all can be tedious.  Moreover, you are limited
  3734.       to the current directory.  Here is a way to use BATUTIL to allow
  3735.       more options.  Make a batch file called l.bat (assuming the Buerg
  3736.       program is called list and is in the path):
  3737.             echo off
  3738.             :again
  3739.             batutil {AT 0F}{CL}{FE %0 message}{set foo=$F(%1)}
  3740.             if %RC%==2 goto clear
  3741.             if a%foo%==a goto clear
  3742.             list %foo%
  3743.             if %RC%==0 goto again
  3744.             goto clear
  3745.             :message
  3746.  
  3747.                Pick File to List
  3748.                <Esc> exits
  3749.  
  3750.             :clear
  3751.             cls
  3752.  
  3753.       If you type in "l" with no filename, you get to pick from a list of
  3754.       all files and from the BATUTIL pick list and when you exit list the
  3755.       list of filenames will be displayed again.  This will happen until
  3756.       you press <Esc>.  If there is a filename or filespec listed, you
  3757.       get a choice from those matching files only.  If there is a unique
  3758.       matching file, then l just calls list and exits when it is done
  3759.       (that is the reason for the test for RC=2).
  3760.  
  3761.             You could make this shell fancier by allowing the user the
  3762.       option of typing in a file spec using $q which you could pass to
  3763.       $f using $f($x(varname)).  To make something like this work, $x
  3764.       translation is done before $f translations.
  3765.  
  3766.  
  3767.       VI.5 A two year olds' delight
  3768.  
  3769.             Here is a simple batch file which delights Barry's two year
  3770.       old daughter
  3771.             for %%a in (1 2 3 4 5 6 7 8 9) do batutil {ge IN}{so 1%%a}
  3772.  
  3773.  
  3774.     Chapter VI:TIPS AND EXAMPLES                               Page 70
  3775.  
  3776.  
  3777.  
  3778.  
  3779.                   Documentation for BATUTIL, Version 1.0 
  3780.  
  3781.  
  3782.       This will wait for the insert key and then play 9 tunes.  The
  3783.       INsert key was especially picked for two reasons: it is large and
  3784.       easy for little hands to reach.  It is not a repeating key so that
  3785.       it is less likely that several keystrokes will get through and
  3786.       abort the tunes.
  3787.  
  3788.  
  3789.       VI.6 Sample batch files
  3790.  
  3791.             You will learn a lot about how to use BATUTIL by studying the
  3792.       sample batch files provided.  We'll make some comments about them
  3793.       here.  One complex nuisance is getting enough environment to run
  3794.       them since it is convenient to store results from BATUTIL in the
  3795.       environment.   If it is your own machine or a client's machine,
  3796.       just be sure to have a large enough environment to begin with.  DOS
  3797.       3.2 and later have a documented switches on the shell command that
  3798.       lets you specify a larger environment.  DOS 3.1 has an undocumented
  3799.       switch.  Various patches to arrange for a larger environment in DOS
  3800.       versions prior to 3.1 are available on BBS systems.
  3801.  
  3802.             But what if you don't know about your users.  At a minimum,
  3803.       you can use the {@Env} command to confirm that there is enough
  3804.       environment for your program and exit if there isn't.  If you know
  3805.       that your batch file will be running on a machine with DOS 3.2 or
  3806.       later, you could try a shell of DOS with the /e command to make a
  3807.       huge environment.  Something like a batch file foo.bat which starts
  3808.       with
  3809.             echo off
  3810.             if (%1)==(restart) goto past
  3811.             %comspec% /c /e:1500 foo restart
  3812.             goto end
  3813.             :past
  3814.             bulk of batch file
  3815.             :end
  3816.       You might add an explicit test for DOS 3.2 or greater using [DOs]
  3817.       and you should certainly use an {@Env} test after the command /c
  3818.       or a {#Env} test before to handle the situation where the user
  3819.       already has a full 1500 byte environment!
  3820.  
  3821.             Perhaps the best method to use is the one exploited in the
  3822.       sample batch files (budemo, equip and input; menudemo uses the
  3823.       simpler halt without 40 bytes free of memory).  One saves the
  3824.       environment to a file, kills the environment and later reloads it
  3825.       from the file.  It is important to have the {KIll} command on the
  3826.  
  3827.  
  3828.     Chapter VI:TIPS AND EXAMPLES                               Page 71
  3829.  
  3830.  
  3831.  
  3832.  
  3833.                   Documentation for BATUTIL, Version 1.0 
  3834.  
  3835.  
  3836.       same command line as the {SAvenv} because if the {SA} is not
  3837.       successful, then BATUTIL will exit and the environment will not be
  3838.       {KI}lled.  In the budemo case,we check for a minimal free
  3839.       environment and so the {set foo..} is added as a check that there
  3840.       wasn't an exit during the {SA}ve.  In the other two files, we can
  3841.       check this with an explicit errorlevel check.  Note that budemo
  3842.       checks for at least 136 bytes of environment.  This is the maximum
  3843.       that you can by sure of after a {SA ...}{KI} when dealing with naive
  3844.       users.  Such users will have the 160 byte environment that DOS
  3845.       gives and they will have the default
  3846.             comspec=C:\command.com
  3847.       22 byte string (and a double ASCII zero) so they'll have 136 bytes
  3848.       free.
  3849.  
  3850.             There is one other device about controlling the environment
  3851.       which is illustrated in budemo.  When DOS makes a shell, it sets up
  3852.       the minimal environment to fit the defined environment of the
  3853.       parent.  Thus, the fact that one has 136 bytes free in the
  3854.       environment when %comspec% /c is called is irrelevant - the child
  3855.       will have less than 16 bytes free!  This is the reason for the
  3856.       strange set a=aaaaa.... and set b=aaaaa...... lines in the budemo
  3857.       file, the fact that the subsidiary files are called with parameters
  3858.       and that they have the set a= and set b= lines.
  3859.  
  3860.             There are two potential problems with the {SA...}{KI}
  3861.       solution.  One is that the user might try to ^Break out of the file
  3862.       and find his environment gone.  The other is that the path won't be
  3863.       there.  In particular, if command.com is not in the current
  3864.       directory, "command" won't work.  Use %comspec% instead - recall
  3865.       that {KI} leaves the comspec variable.
  3866.  
  3867.             Other than the environment, budemo is rather straightforward.
  3868.       It uses the {fecho %0} and goto fmenu%RC% tricks discussed in
  3869.       section 1.  It turns the cursor off with the
  3870.             set cur=off
  3871.       command.
  3872.  
  3873.             Soundemo.bat is also straightforward.  Note the way the
  3874.       fpretty command is used to produce the second screen with its
  3875.       special box.
  3876.  
  3877.             Showdemo's most interesting feature may be the last panel
  3878.       that illustrates how to use the fpretty command for a display of
  3879.       different columns in different colors.  Note the use of the $$.
  3880.  
  3881.  
  3882.     Chapter VI:TIPS AND EXAMPLES                               Page 72
  3883.  
  3884.  
  3885.  
  3886.  
  3887.                   Documentation for BATUTIL, Version 1.0 
  3888.  
  3889.  
  3890.             Note inputdem's use of $L with spaces after it.
  3891.  
  3892.             Note that equip gets all its information and saves it in the
  3893.       environment and then displays it all at once.
  3894.  
  3895.             The study of these samples should give you an idea of how to
  3896.       use BATUTIL.
  3897.  
  3898.  
  3899.  
  3900.  
  3901.  
  3902.  
  3903.  
  3904.  
  3905.  
  3906.  
  3907.  
  3908.  
  3909.  
  3910.  
  3911.  
  3912.  
  3913.  
  3914.  
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.  
  3921.  
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.     Chapter VI:TIPS AND EXAMPLES                               Page 73
  3937.  
  3938.  
  3939.  
  3940.  
  3941.                    Chapter VII:COMMAND REFERENCE
  3942.  
  3943.       In this chapter, we present an alphabetical list of commands with a
  3944.       complete reference for each command in the following format:
  3945.  
  3946.       COMMAND         []/{}       Input: INPUT        Output:  OUTPUT
  3947.             Parameters: LIST
  3948.             DESCRIPTION
  3949.             Values: LIST
  3950.             Manual reference: LIST
  3951.             Examples: SAMPLES
  3952.             Internal parameters: LIST
  3953.             See also: LIST
  3954.       ----------------------------------------------------------------------
  3955.       Here after each command appears []/{} or just {} to indicate whether
  3956.       the command can appear on the command line only within {} or if [] is
  3957.       also allowed.  The items in CAPS change from item to item.
  3958.           Input is one or more of the following (inside [] we indicate
  3959.       the abbreviation used):
  3960.             Cmdline [CM]        indicates the command takes parameters
  3961.             System  [SY]        indicates that it reads the internals of
  3962.                                   your computer
  3963.             Batutil [BU]        uses internal flags in BATUTIL
  3964.             User    [US]        input from user required
  3965.             File    [FI]        text in a file between sets of labels
  3966.           Output is one or more of the following (inside [] we indicate
  3967.       the abbreviation used):
  3968.             Errorlevel [EL]     sets errorlevel and/or the variable RC
  3969.             Environment [EN]    effects one or more environmental variables
  3970.             Display  [DI]       displays on screen or speaker
  3971.             Internal [IN]       if an internal flag like CS is effected
  3972.           Values only appears if the commands returns one of a set of
  3973.       numbers and lists those values.  Internal parameters lists the
  3974.       internal flags (if any) like CS which BATUTIL keeps and which
  3975.       effect the command.  Manual reference gives cross references to the
  3976.       manual.
  3977.  
  3978.       ----------------------------------------------------------------------
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.  
  3985.  
  3986.  
  3987.  
  3988.  
  3989.  
  3990.     Chapter VII:COMMAND REFERENCE                              Page 74
  3991.  
  3992.  
  3993.  
  3994.  
  3995.                   Documentation for BATUTIL, Version 1.0 
  3996.  
  3997.  
  3998.       #Altmon         []/{}       Input: SY           Output: EL
  3999.             Parameters: None
  4000.             Returns the type of a second monitor, if any
  4001.             Values:
  4002.                0 = none                   8 = vga color
  4003.                1 = monochrome  (MDA)     11 = mcga mono
  4004.                2 = cga color             12 = mcga color
  4005.                4 = ega color             21 = hercules mono
  4006.                5 = ega mono              22 = hercules monochrome plus
  4007.                6 = prof. graphics        23 = hercules Incolor
  4008.                7 = vga mono              99 = unknown
  4009.             Manual reference: Section II.4
  4010.             Examples: BATUTIL [#A]
  4011.             See also: #Terminal, #Whichmon, @Terminal
  4012.       ----------------------------------------------------------------------
  4013.       #Comm           []/{}       Input: SY           Output: EL
  4014.             Parameters: None
  4015.             Returns the number of comm ports from 0 to 4 as determined from
  4016.       non-zero addresses in the BIOS area.  If there are more than two comm
  4017.       ports, this number may not be accurate since DOS only supports two comm
  4018.       ports and some non-standard method may be used by the system.
  4019.             Values: 0 through 4
  4020.             Manual reference: Section II.5
  4021.             Examples: BATUTIL [#C]
  4022.       ----------------------------------------------------------------------
  4023.       #Disk           []/{}       Input: SY           Output: EL
  4024.             Parameters: Drive letter; no parameter means default drive
  4025.             This command returns the total disk space; for drives A and B in
  4026.       units of 8K; for other drives in units of 256K; rounded down; capped at
  4027.       199.
  4028.             Values: 0 to 199; 239 means invalid drive letter or drive not
  4029.       ready
  4030.             Manual reference: Section II.3
  4031.             Examples: BATUTIL [#D C]
  4032.             See also: @Disk
  4033.       ----------------------------------------------------------------------
  4034.       #Env            []/{}       Input: SY           Output: EL
  4035.             Parameters: None
  4036.             Total environment space in units of 16 bytes up to 3184.
  4037.             Values: 0 to 199 (199 for 3184 bytes of environment or more)
  4038.             Manual reference: Section II.3
  4039.             Examples: BATUTIL [#E]
  4040.             See also: @Env
  4041.       ----------------------------------------------------------------------
  4042.  
  4043.  
  4044.     Chapter VII:COMMAND REFERENCE                              Page 75
  4045.  
  4046.  
  4047.  
  4048.  
  4049.                   Documentation for BATUTIL, Version 1.0 
  4050.  
  4051.  
  4052.       #Floppy         []/{}       Input: SY           Output: EL
  4053.             Parameters: None
  4054.             Number of floppy drives as reported by the BIOS equipment byte
  4055.             Values: 0 to 4
  4056.             Manual reference: Section II.5
  4057.             Examples: BATUTIL [#F]
  4058.             See also: @Floppy
  4059.       ----------------------------------------------------------------------
  4060.       #Game           []/{}       Input: SY           Output: EL
  4061.             Parameters: None
  4062.             Number of game ports as reported by the BIOS equipment byte
  4063.             Values: 0 or 1
  4064.             Manual reference: Section II.5
  4065.             Examples: BATUTIL [#G]
  4066.       ----------------------------------------------------------------------
  4067.       #Intel          []/{}       Input: SY           Output: EL
  4068.             Parameters: None
  4069.             Returns the CPU type.
  4070.             Values: 0 = 8086/8088; 1 = 80186; 2 = 80286; 3 = 80386;
  4071.               20 = NEC V20/V30
  4072.             Manual reference: Section II.5
  4073.             Examples: BATUTIL [#I]
  4074.             See also: @Intel
  4075.       ----------------------------------------------------------------------
  4076.       #Keyboard       []/{}       Input: SY           Output: EL
  4077.             Parameters: None
  4078.             Tests for the presence of BIOS support for the enhanced (101 key)
  4079.       keyboard
  4080.             Values: 0 = not enhanced; 1 = enhanced
  4081.             Manual reference: Section II.4
  4082.             Examples: BATUTIL [#K]
  4083.       ----------------------------------------------------------------------
  4084.       #Lim            []/{}       Input: SY           Output: EL
  4085.             Parameters: None
  4086.             Reports the total amount of Lotus Intel Microsoft Expanded memory
  4087.       in units of 64K up to 12736 K (rounded down)
  4088.             Values: 0 to 199 (0 if no EMS)
  4089.             Manual reference: Section II.3
  4090.             Examples: BATUTIL [#L]
  4091.             See also: LIm, #Mem, #Xtended, @Lim, @Mem, @Xtended
  4092.       ----------------------------------------------------------------------
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.     Chapter VII:COMMAND REFERENCE                              Page 76
  4099.  
  4100.  
  4101.  
  4102.  
  4103.                   Documentation for BATUTIL, Version 1.0 
  4104.  
  4105.  
  4106.       #Mem            []/{}       Input: SY           Output: EL
  4107.             Parameters: None
  4108.             Returns the total DOS memory in units of 4K rounded down (640K
  4109.       corresponds to 160; because PS/2's have only 639K, 159 will be
  4110.       reported)
  4111.             Values: 0 to 160
  4112.             Manual reference: Section II.3
  4113.             Examples: BATUTIL [#M]
  4114.             See also: #Lim, #Xtended, @Lim, @Mem, @Xtended
  4115.       ----------------------------------------------------------------------
  4116.       #Prn            []/{}       Input: SY           Output: EL
  4117.             Parameters: None
  4118.             Returns the number of printer ports (to which printers may or may
  4119.       not be attached)
  4120.             Values: 0 to 3
  4121.             Manual reference: Section II.5
  4122.             Examples: BATUTIL [#P]
  4123.             See also: @Prn
  4124.       ----------------------------------------------------------------------
  4125.       #Rodent         []/{}       Input: SY           Output: EL
  4126.             Parameters: None
  4127.             Returns 0 if no mouse; 1 if a mouse is present
  4128.             Values: 0 or 1
  4129.             Manual reference: Section II.4
  4130.             Examples: BATUTIL [#R]
  4131.       ----------------------------------------------------------------------
  4132.       #Terminal       []/{}       Input: SY           Output: EL
  4133.             Parameters: None, R, S or C
  4134.             Returns 1 or 2 depending on the number of monitors if
  4135.               no parameter; number of Rows, Columns or Special=Rows - 1
  4136.             Values: 1 or 2; R=25,43,50 typically;  C=40 or 80 typically
  4137.             Manual reference: Section II.4
  4138.             Examples: BATUTIL [#T]; BATUTIL {#T R}{ec Screen has $x(rc) rows}
  4139.             See also: @Terminal, #Altmon, #Whichmon
  4140.       ----------------------------------------------------------------------
  4141.       #Vmode          []/{}       Input: SY           Output: EL
  4142.             Parameters: None
  4143.             Returns the currently active mode, e.g. 7 for monochrome text, 2
  4144.       or 3 for text on a graphics monitor, 16 for EGA hires graphics, etc.
  4145.             Values: 1 to 16
  4146.             Manual reference: Section II.4
  4147.             Examples: BATUTIL [#V]
  4148.             See also: #Terminal, #Altmon, #Whichmon, @Terminal
  4149.       ----------------------------------------------------------------------
  4150.  
  4151.  
  4152.     Chapter VII:COMMAND REFERENCE                              Page 77
  4153.  
  4154.  
  4155.  
  4156.  
  4157.                   Documentation for BATUTIL, Version 1.0 
  4158.  
  4159.  
  4160.       #Whichmon       []/{}       Input: SY           Output: EL
  4161.             Parameters: None
  4162.             Returns the type of the currently active monitor
  4163.             Values:                       8 = vga color
  4164.                1 = monochrome  (MDA)     11 = mcga mono
  4165.                2 = cga color             12 = mcga color
  4166.                4 = ega color             21 = hercules mono
  4167.                5 = ega mono              22 = hercules monochrome plus
  4168.                6 = prof. graphics        23 = hercules Incolor
  4169.                7 = vga mono              99 = unknown
  4170.             Manual reference: Section II.4
  4171.             Examples: BATUTIL [#W]
  4172.             See also: #Terminal, #Altmon, #Vmode, @Terminal
  4173.       ----------------------------------------------------------------------
  4174.       #Xtended        []/{}       Input: SY           Output: EL
  4175.             Parameters: None
  4176.             Amount of AT extended memory in units of 64K rounded down up to a
  4177.       maximum of 12736K; with more than that 199 is returned. On an 80386
  4178.       machine with 386 control software, this number may not be reliable.
  4179.             Values: 0 to 199
  4180.             Manual reference: Section II.3
  4181.             Examples: BATUTIL [#X]
  4182.             See also: #Lim, #Mem, @Lim, @Mem, @Xtended
  4183.       ----------------------------------------------------------------------
  4184.       $A,$a,$B,$C in diverse cmd    Input: SY, CM       Output:  EN,DI
  4185.             Parameters: Filespec in ()
  4186.             Parses the file spec in (); $a gives path; $A path with trailing
  4187.       backspace; $B the filename and $C the extension.
  4188.             Manual reference: Section III.2
  4189.             Examples: BATUTIL {SE file=$f(*.bat) ext=$C($x(file))}
  4190.             See also: SEt, $F
  4191.       ----------------------------------------------------------------------
  4192.       $F or $f  in SEt command    Input: SY, CM, US   Output:  EN
  4193.             Parameters: None or filespec in ()
  4194.             Calls up a file list from which the user can pick a file which
  4195.       then replaces $f in the SEt command
  4196.             Values: 0 = file picked; 1 = unique matching file;
  4197.               2 = Exit with <Esc>;  3 = Invalid path
  4198.               4 = No wildcards - file not found;  9 = Invalid path
  4199.             Manual reference: Section V.5
  4200.             Examples: BATUTIL {EC Pick a batch file}{SE file=$f(*.bat)}
  4201.             Internal parameters: FDIR
  4202.             See also: SEt, FDir, $A,a,B,C
  4203.       ----------------------------------------------------------------------
  4204.  
  4205.  
  4206.     Chapter VII:COMMAND REFERENCE                              Page 78
  4207.  
  4208.  
  4209.  
  4210.  
  4211.                   Documentation for BATUTIL, Version 1.0 
  4212.  
  4213.  
  4214.       $L  in Echo command         Input: CM, SY       Output:  IN
  4215.             Parameters: None
  4216.             The place where $L would have appeared is remembered by
  4217.       BATUTIL and a subsequent GEtkey with a WAit will have a ticking
  4218.       clock placed in the place.  You must place explicit spaces in the
  4219.       echoed string
  4220.             Manual reference: Section IV.5
  4221.             Examples: BATUTIL {EC Today is $E and you have $L   seconds
  4222.                          left}{GE WA60}
  4223.             Internal parameters: TimeRow, TimeCol
  4224.             See also: ROw, COl, ATtribute
  4225.       ----------------------------------------------------------------------
  4226.       $Q or $?  in SEt command    Input: US, BU       Output:  EN
  4227.             Parameters: None
  4228.             In the midst of a SEt string, $Q and $? pause to get a string
  4229.       input from the user and that string then replaces the $Q or $?.  $Q
  4230.       uses a standard (===>) prompt and standard colors.  $? allows you
  4231.       to set colors with the AT/MN commands and puts no special prompt in.
  4232.             Manual reference: Section V.4
  4233.             Examples: BATUTIL {EC What is your name?$_}{SE name=$Q}
  4234.             Internal parameters: ?Length, ?Size
  4235.             See also: SEt, ?Length, ?Size, QUery, AT, MN
  4236.       ----------------------------------------------------------------------
  4237.       $X or $x  in diverse cmds   Input: EN           Output: EN, DI
  4238.             Parameters: Variable name in ()
  4239.             $x(varname) searches the environment for a variable varname
  4240.       and if it finds it replaces $x(varname) by it value.  Otherwise
  4241.       $x(varname) is replaced by the empty string.  $X translates the
  4242.       value of the variable using metastring translation.  Applies to
  4243.       ECho, PRetty, MEnu, SEt commands
  4244.             Manual reference: Section III.2
  4245.             Examples: BATUTIL {EC your PATH is $x(path)}
  4246.             Internal parameters: $Translate
  4247.             See also: ECho, FEcho, PRetty, FPretty, MEnu, FMenu, SEt
  4248.       ----------------------------------------------------------------------
  4249.  
  4250.  
  4251.  
  4252.  
  4253.  
  4254.  
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.     Chapter VII:COMMAND REFERENCE                              Page 79
  4261.  
  4262.  
  4263.  
  4264.  
  4265.                   Documentation for BATUTIL, Version 1.0 
  4266.  
  4267.  
  4268.       $<letter> in diverse cmds   Input: SY           Output: EN, DI
  4269.             Parameters: $ followed by $,t,p,d,v,n,g,l,b,q,h,e,_,P,T,M,D,Y,
  4270.                W,E,H,m,S,^,(,),`,'
  4271.             In various places (ECho, PRetty, MEnu, SEt) $<letter> is
  4272.       translated according to DOS prompt metastring rules, SEND/STACKEY
  4273.       extensions and some special BATUTIL extensions.  See the list in
  4274.       section III.2
  4275.             Manual reference: Section III.2
  4276.             Examples: BATUTIL {EC Today is $E}
  4277.             Internal parameters: $Translate
  4278.             See also: ECho, FEcho, PRetty, FPretty, MEnu, FMenu, SEt
  4279.       ----------------------------------------------------------------------
  4280.       $Translate      {}          Input: CM           Output: IN
  4281.             Parameters: none or -
  4282.             {$T -} sets an internal flag turning off translation of $letter
  4283.       metastrings in the set, echo and menu commands.  $T undoes the effect
  4284.       of $T -.  BATUTIL does not keep internal flags from one running to the
  4285.       next so $ translation is turned back on for each new loading.
  4286.             Manual reference: Section III.2
  4287.             Examples: BATUTIL {$T-}{EC $E}{$T}{EC $Shi $E}
  4288.               would echo "$E hi July 23, 1988" on July 23, 1988
  4289.             See also: ^Translate, QUery
  4290.       ----------------------------------------------------------------------
  4291.       ? or !   HELP   Initial Parameter               Output:  IN
  4292.             Parameters: Only first two letters count
  4293.             If ? (not in {} or []) is the first parameter on the command
  4294.       line, help is called and the rest of the command line is ignored
  4295.       except that if the first two letters (or first two letters after a
  4296.       { or [) match a command, help for that command is displayed rather
  4297.       than the main help menu.  For help to be available, batutil.hlp
  4298.       must be in the default directory or in your path.
  4299.             ! works the same as ? except that ? has some fancy visual effects
  4300.       and ! suppresses them.
  4301.             Manual reference: I.3
  4302.             Examples: BATUTIL ? getkey
  4303.       ----------------------------------------------------------------------
  4304.       ?Length         {}          Input: CM           Output: IN
  4305.             Parameters: 1 to 255 (default is 80)
  4306.             Adjusts the maximum length of user input to a $Q or $? in a set
  4307.       command
  4308.             Manual reference: Section V.4
  4309.             Examples: BATUTIL {EC Enter your name}{?L 30}{set foo=$Q}
  4310.             See also: ?Size, SEt
  4311.       ----------------------------------------------------------------------
  4312.  
  4313.  
  4314.     Chapter VII:COMMAND REFERENCE                              Page 80
  4315.  
  4316.  
  4317.  
  4318.  
  4319.                   Documentation for BATUTIL, Version 1.0 
  4320.  
  4321.  
  4322.       ?Size           {}          Input: CM           Output: IN
  4323.             Parameters: 1 to 80
  4324.             Adjusts the size of the edit box for the $Q or $? in a set
  4325.       command
  4326.             Values: 1 to 80 (default is 50); if ?L is less than ?S, then ?S
  4327.       is adjusted downwards
  4328.             Manual reference: Section V.4
  4329.             Examples: BATUTIL {EC Enter your name}{?L 30}{?S 20}{set foo=$Q}
  4330.             See also: ?Length, SEt
  4331.       ----------------------------------------------------------------------
  4332.       @Ansi           []/{}       Input: SY           Output: EL
  4333.             Parameters: None
  4334.             Determines if there is an ANSI compatible screen driver present
  4335.       (by saving the current screen and using an ANSI command to move the
  4336.       cursor and checking that the cursor really moved).
  4337.             Values: 0 = No ANSI driver; 1 = ANSI driver found
  4338.             Manual reference: Section II.4
  4339.             Examples: BATUTIL [@A]
  4340.       ----------------------------------------------------------------------
  4341.       @Disk           []/{}       Input: SY           Output: EL
  4342.             Parameters: Drive letter; no parameter means default drive
  4343.             Free disk space on the specified or default drive in units of 8K
  4344.       rounded down with 199 returned for 1592K or more free
  4345.             Values: 0 to 199; 239 means invalid drive letter or drive not
  4346.       ready
  4347.             Manual reference: Section II.3
  4348.             Examples: BATUTIL [@D C]
  4349.             See also: #Disk
  4350.       ----------------------------------------------------------------------
  4351.       @Env            []/{}       Input: SY           Output: EL
  4352.             Parameters: None
  4353.             Number of bytes of free environment with 199 returned if there
  4354.       are 199 or more free bytes.  This is information about the current
  4355.       ACTIVE DOS environment.
  4356.             Values: 1 to 199
  4357.             Manual reference: Section II.3
  4358.             Examples: BATUTIL [@E]
  4359.             See also: #Env
  4360.       ----------------------------------------------------------------------
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.  
  4367.  
  4368.     Chapter VII:COMMAND REFERENCE                              Page 81
  4369.  
  4370.  
  4371.  
  4372.  
  4373.                   Documentation for BATUTIL, Version 1.0 
  4374.  
  4375.  
  4376.       @Floppy         []/{}       Input: SY           Output: EL
  4377.             Parameters: None
  4378.             For use in systems with a single floppy drive which can be either
  4379.       drive A or B
  4380.             Values: 0 = other than one floppy; 1 = single floppy currently
  4381.       set to drive A; 2= single floppy currently set to drive B
  4382.             Manual reference: Section II.5
  4383.             Examples: BATUTIL [@F]
  4384.             See also: #Floppy
  4385.       ----------------------------------------------------------------------
  4386.       @Intel          []/{}       Input: SY           Output: EL
  4387.             Parameters: None
  4388.             Returns information on the type of math coprocessor present
  4389.             Values: 0 = no '87 chip, 1 = 8087, 2= 80287, 3 = 80387
  4390.             Manual reference: Section II.5
  4391.             Examples: BATUTIL
  4392.             See also: #Intel
  4393.       ----------------------------------------------------------------------
  4394.       @Lim            []/{}       Input: SY           Output: EL
  4395.             Parameters: None
  4396.             Returns the amount of free EMS memory in units of 16K rounded
  4397.       down up to 3184K or more which returns 199
  4398.             Values: 0 to 199
  4399.             Manual reference: Section II.3
  4400.             Examples: BATUTIL [@L]
  4401.             See also: LIm, #Lim, #Mem, #Xtended, @Mem, @Xtended
  4402.       ----------------------------------------------------------------------
  4403.       @Mem            []/{}       Input: SY           Output: EL
  4404.             Parameters: None
  4405.             Free DOS memory in units of 4K rounded down
  4406.             Values: 0 to 160
  4407.             Manual reference: Section II.3
  4408.             Examples: BATUTIL [@M]
  4409.             See also: #Lim, #Mem, #Xtended, @Lim, @Xtended
  4410.       ----------------------------------------------------------------------
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.     Chapter VII:COMMAND REFERENCE                              Page 82
  4423.  
  4424.  
  4425.  
  4426.  
  4427.                   Documentation for BATUTIL, Version 1.0 
  4428.  
  4429.  
  4430.       @Prn            []/{}       Input: SY           Output: EL
  4431.             Parameters: printer number from 1 to 3, no parameter defaults to
  4432.       LPT1
  4433.             Returns information about the status of the printer whose number
  4434.       is given as a parameter.
  4435.             Values: returns information about printer as follows:
  4436.                0 = printer status OK
  4437.                1 = paper out error
  4438.                2 = I/O error
  4439.                3 = Timeout error
  4440.                4 = invalid printer
  4441.                5 = other printer error
  4442.             Manual reference: Section II.5
  4443.             Examples: BATUTIL [@P 2]
  4444.             See also: #Prn
  4445.       ----------------------------------------------------------------------
  4446.       @Terminal       []/{}       Input: SY           Output: EL
  4447.             Parameters: None
  4448.             Returns the active monitor
  4449.             Values: 0 = monochrome (including Hercules monographics);
  4450.                1= graphics monitor (CGA, EGA, VGA)
  4451.             Manual reference: Section II.4
  4452.             Examples: BATUTIL  [@T]
  4453.             See also: #Terminal, #Altmon, #Whichmon
  4454.       ----------------------------------------------------------------------
  4455.       @Xtended        []/{}       Input: SY           Output: EL
  4456.             Parameters: None
  4457.             Returns the amount of free extended memory in units of 16K.
  4458.       Since there is no standard for extended memory, BATUTIL may think that
  4459.       some memory which is used by an application is actually free.  It takes
  4460.       into account any VDISK compatible usage.
  4461.             Values: 0 to 199
  4462.             Manual reference: Section II.3
  4463.             Examples: BATUTIL [@X]
  4464.             See also: #Lim, #Mem, #Xtended, @Lim, @Mem
  4465.       ----------------------------------------------------------------------
  4466.  
  4467.  
  4468.  
  4469.  
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.     Chapter VII:COMMAND REFERENCE                              Page 83
  4477.  
  4478.  
  4479.  
  4480.  
  4481.                   Documentation for BATUTIL, Version 1.0 
  4482.  
  4483.  
  4484.       ^Translate      {}          Input: CM           Output: IN
  4485.             Parameters: None or -
  4486.             {^T -} sets an internal flag turning off translation of ^letter
  4487.       metastrings in the set, echo and menu commands.  ^T undoes the effect
  4488.       of ^T -.  BATUTIL does not keep internal flags from one running to the
  4489.       next so ^ translation is turned back on for each new loading.
  4490.             Manual reference: Section III.2
  4491.             Examples: BATUTIL {^T -}{EC ^A}{^T}{EC ^A}
  4492.               would echo the letters ^A and then happy face (= ctrl-A)
  4493.             See also: $Translate, QUery
  4494.       ----------------------------------------------------------------------
  4495.       ADdpath         []/{}       Input: CM           Output: EN,EL
  4496.             Parameters: list of paths separated by spaces; $p or $P processed
  4497.             Adds the indicated paths to the PATH unless they are already in
  4498.       the path statement.  $p is replaced by the current path and $P by the
  4499.       current path with a trailing backslash.
  4500.             Values: 0 to 199 - number of directories actually added to the
  4501.       PATH
  4502.             Manual reference: Section V.7
  4503.             Examples: BATUTIL [AD $p] would add the current directory to the
  4504.       path
  4505.             See also: DElpath, PAthedit, EDitenv
  4506.       ----------------------------------------------------------------------
  4507.       ASciiread       []/{}       Input: US           Output: EL
  4508.             Parameters: None
  4509.             Waits for a keystroke and reports the ASCII value of the
  4510.       key struck (0 for extended keys like <F1>)
  4511.             Values: 0 to 255
  4512.             Manual reference: Section IV.6
  4513.             Examples: BATUTIL [AS]
  4514.             Internal parameters: NFlush (determines whether the keyboard is
  4515.       flushed)
  4516.             See also: SCanread, GEtkey, NFlush
  4517.       ----------------------------------------------------------------------
  4518.  
  4519.  
  4520.  
  4521.  
  4522.  
  4523.  
  4524.  
  4525.  
  4526.  
  4527.  
  4528.  
  4529.  
  4530.     Chapter VII:COMMAND REFERENCE                              Page 84
  4531.  
  4532.  
  4533.  
  4534.  
  4535.                   Documentation for BATUTIL, Version 1.0 
  4536.  
  4537.  
  4538.       ATtribute       {}          Input: CM           Output: IN
  4539.             Parameters: Hex number from 0 to FF with optional leading $;
  4540.       special meaning if the parameter is T followed by a one or two
  4541.       digit number.
  4542.             BATUTIL keeps an internal attribute used when EChoing, for
  4543.       shadows in MEnus, when the CLs command clears the screen,for the $?
  4544.       command.  It defaults to $1E (yellow on blue).  The {AT xx} changes it.
  4545.       See section III.3 for a list of attributes. Two special values do not
  4546.       have their default meaning: $55 uses the attribute at the cursor at the
  4547.       time that ECho is called; $66 write with no change in the underlying
  4548.       attributes.  {AT Tnm} effects how the time is displayed in a
  4549.       {GEtkey WAit...} command: n from 0-3 (default 3) effects how much
  4550.       time is adjusted and m from 1 to 8, the units used in 1/4 seconds
  4551.       (default is 4; i.e. 1 second).
  4552.             Manual reference: Section III.3, Section IV.5
  4553.             Examples: BATUTIL {EC hello$S}{AT $4F}{EC there}   would echo
  4554.       "hello " in yellow on blue and "there" in white on red.
  4555.             See also: MNattribute, ECho, PRetty, CLs, EOline, ROw, COl
  4556.       ----------------------------------------------------------------------
  4557.       BEcho           {}          Input: CM, BU       Output: DI
  4558.             Parameters: string to be echoed (special handling of leading
  4559.       ~ and trailing ~ or ^)
  4560.             Echoes a string with large (8x8) characters to the screen
  4561.       with metastring translation and an automatic big CR.  Colors
  4562.       determined by the AT and MN flags (defaulting to $1E on color and
  4563.       $07 on monochrome).  A final ^ on the string suppress the big CR.
  4564.       Dot patterns for letters replaced by space for off dots and ASCII
  4565.       219 for on.  This can be changed by the BIgchar command.  See that
  4566.       description for the treatment of leading/trailing  ~'s.
  4567.             Manual reference: Section III.5
  4568.             Examples: BATUTIL {BE hi there!}
  4569.             Internal parameters: AT, MN, BI, $T, ^T
  4570.             See also: ECho, PRetty, BPretty, ATttribute, MNattribute,
  4571.                 BIgchar
  4572.       ----------------------------------------------------------------------
  4573.  
  4574.  
  4575.  
  4576.  
  4577.  
  4578.  
  4579.  
  4580.  
  4581.  
  4582.  
  4583.  
  4584.     Chapter VII:COMMAND REFERENCE                              Page 85
  4585.  
  4586.  
  4587.  
  4588.  
  4589.                   Documentation for BATUTIL, Version 1.0 
  4590.  
  4591.  
  4592.       BIgchar         {}          Input: CM           Output: IN
  4593.             Parameters: one or two ASCII characters.  Each character can
  4594.       be replaced by a number from 01 to 255 (use leading 0 for numbers
  4595.       below 10) or a hex number preceded by a $.
  4596.             BEcho and BPretty display large letters based on the dot
  4597.       patterns stored in ROM.  On dots are replaced by an "on character"
  4598.       and off dots by an "off character" which default to ASCII 219
  4599.       (solid block) and ASCII 32 (space).  BIgchar allows you to change
  4600.       that - the first parameter is the on character and the second the
  4601.       off character.  If the on character is ASCII 255, then the on
  4602.       character displayed is the same as the character being displayed.
  4603.       By default for BEcho, the background character is different from
  4604.       space is displayed on the entire line; leading and trailing ~'s
  4605.       will suppress that.
  4606.             Manual reference: Section III.5
  4607.             Examples: BATUTIL {BI $20 01}{BP @1FH@1Ei}
  4608.             See also: BEcho, BPretty
  4609.       ----------------------------------------------------------------------
  4610.       BPretty         {}          Input: CM, BU       Output: DI
  4611.             Parameters: string to be echoed with embedded @ commands
  4612.       (special handling of trailing ~)
  4613.             Echoes a string with large (8x8) characters to the screen
  4614.       with metastring translation and an automatic big CR.  Colors
  4615.       determined by the AT and MN flags (defaulting to $1E on color and
  4616.       $07 on monochrome).  A final ^ on the string suppress the big CR.
  4617.       Dot patterns for letters replaced by space for off dots and ASCII
  4618.       219 for on.  This can be changed by the BIgchar command. Colors can
  4619.       be changed by @'s in the string to be printed; see the PRetty
  4620.       command.
  4621.             Manual reference: Section III.5
  4622.             Examples: BATUTIL {BP @1FH@1Ei}
  4623.             Internal parameters: AT, MN, BI, $T, ^T
  4624.             See also: ECho, PRetty, BEcho, ATttribute, MNattribute,
  4625.                 BIgchar
  4626.       ----------------------------------------------------------------------
  4627.       CArousel        []/{}       Input: SY           Output: EL
  4628.             Parameters: None
  4629.             CArousel is special to Softlogic's SOFTWARE CAROUSEL.  It returns
  4630.       0 is CArousel isn't loaded and otherwise returns the current partition
  4631.       number from 1 to 10 (1 to 12 with Carousel 3.0)
  4632.             Values: 0 to 12
  4633.             Manual reference: Section II.2
  4634.             Examples: BATUTIL [CA]
  4635.       ----------------------------------------------------------------------
  4636.  
  4637.  
  4638.     Chapter VII:COMMAND REFERENCE                              Page 86
  4639.  
  4640.  
  4641.  
  4642.  
  4643.                   Documentation for BATUTIL, Version 1.0 
  4644.  
  4645.  
  4646.       CHeck           []/{}       Input: CM, SY       Output: EL
  4647.             Parameters: Path with or without trailing backslash
  4648.             Determines whether a given path is present in the system
  4649.             Values: 0 = path valid; 9 = path not found
  4650.             Manual reference: Section II.6
  4651.             Examples: BATUTIL {CH C:\bin}
  4652.             See also: EXist
  4653.       ----------------------------------------------------------------------
  4654.       CLs             {}          Input: BU           Output: DI
  4655.             Parameters: None
  4656.             Clears the screen in the current internal attributes which are
  4657.       $1E (yellow on blue) by default on a graphics screen and $07 (normal)
  4658.       on a monochrome screen; may be changed with the AT and MN commands
  4659.             Manual reference: Section III.3
  4660.             Examples: BATUTIL {AT $1F}{CL} would clear the screen in white on
  4661.       red (!)
  4662.             See also: ATtribute, MNattribute, EOline
  4663.       ----------------------------------------------------------------------
  4664.       COl             {}          Input: CM           Output: DI
  4665.             Parameters: One decimal number with optional +, - or T in front;
  4666.       decimal number must be between 1 and 80.
  4667.             Moves the cursor; if just a number is given the cursor is moved
  4668.       to precisely that column.  If a plus or minus precedes the number,
  4669.       then the movement is relative to the current position but wrapping
  4670.       does not take place so that, for example {CO +80} will always go to
  4671.       column 80.  {CO Txx} sets the location of where the countdown clock
  4672.       will occur with {GEtkey WAit}
  4673.             Manual reference: Section III.7, Section IV.5
  4674.             Examples: BATUTIL {CO 5}{EC This line is indented}
  4675.                       BATUTIL {RO 1}{EC Time Left:}{RO T1}{CO T12}{GE WA60}
  4676.             See also: ROw, CUrsor
  4677.       ----------------------------------------------------------------------
  4678.       CSent           {}          Input: None         Output: IN
  4679.             Parameters: None
  4680.             Input for GEtkey, PMatch and USername are not case sensitive by
  4681.       default; CSent will tell the next call to either of these to be case
  4682.       sensitive.  The internal flag is reset by such a call.
  4683.             Manual reference: Section IV.5
  4684.             Examples: BATUTIL {CS}{GE Y N}{GE Y N}  ; the first call would
  4685.       require Y or N; the second would accept Y,y,N or n
  4686.             See also: GEtkey, PMatch, USername
  4687.       ----------------------------------------------------------------------
  4688.  
  4689.  
  4690.  
  4691.  
  4692.     Chapter VII:COMMAND REFERENCE                              Page 87
  4693.  
  4694.  
  4695.  
  4696.  
  4697.                   Documentation for BATUTIL, Version 1.0 
  4698.  
  4699.  
  4700.       CUrsor          {}          Input: CM           Output: DI
  4701.             Parameters: + or - required
  4702.             Turns off the Cursor if a minus is used; turns it back on if a +
  4703.       is used.  In either case, the cursor is turned back on when BATUTIL
  4704.       exits.
  4705.             Manual reference: Section III.7
  4706.             Examples: BATUTIL {CU}{EC hit any key}{AS}
  4707.             See also: ROw, COl
  4708.       ----------------------------------------------------------------------
  4709.       DAte            []/{}       Input: None         Output: EL
  4710.             Parameters: None
  4711.             Returns the day of the month from 1 to 31
  4712.             Values: 1 to 31
  4713.             Manual reference: Section II.2
  4714.             Examples: BATUTIL [DA]
  4715.             See also: HOur, MInute, WEekday, MOnth, YEar
  4716.       ----------------------------------------------------------------------
  4717.       DElpath         []/{}       Input: CM           Output: EN,EL
  4718.             Parameters: list of paths separated by spaces; $p or $P processed
  4719.             Deletes the indicated paths from the PATH if they are in the path
  4720.       statement.  $p is replaced by the current path and $P by the current
  4721.       path with a trailing backslash.
  4722.             Values: 0 to 199 - number of directories actually removed
  4723.       from the PATH
  4724.             Manual reference: Section V.7
  4725.             Examples: BATUTIL [DE $p] would remove the current directory from
  4726.       the path
  4727.             See also: ADdpath, PAthedit, EDitenv
  4728.       ----------------------------------------------------------------------
  4729.       DOs             []/{}       Input: None         Output: EL
  4730.             Parameters: None or 4
  4731.             Returns the DOS version times ten rounded downwards.
  4732.             "DOS 4" returns 1 if 4DOS is loaded in memory and 0 if not
  4733.             Values: 20,21,30,31,32,33,40 (should work on later versions)
  4734.                     0,1 for "DOS 4"
  4735.             Manual reference: Section II.3
  4736.             Examples: BATUTIL [DO]
  4737.       ----------------------------------------------------------------------
  4738.  
  4739.  
  4740.  
  4741.  
  4742.  
  4743.  
  4744.  
  4745.  
  4746.     Chapter VII:COMMAND REFERENCE                              Page 88
  4747.  
  4748.  
  4749.  
  4750.  
  4751.                   Documentation for BATUTIL, Version 1.0 
  4752.  
  4753.  
  4754.       DRive           []/{}       Input: None         Output: EL
  4755.             Parameters: None
  4756.             DRive returns the current drive with 0=A, 1=B, ...., 25=Z. This is
  4757.       the drive as DOS reports it so if SUBST is in effect, the subst letter
  4758.       will be used.
  4759.             Values: 0 to 25
  4760.             Manual reference: Section II.3
  4761.             Examples: BATUTIL [DR]
  4762.             See also: #Disk, @Disk
  4763.       ----------------------------------------------------------------------
  4764.       DView           []/{}       Input: SY           Output: EL
  4765.             Parameters: None
  4766.             Dview is special to Quarterdeck's DESQVIEW multitasking
  4767.       software.  It returns 0 is DesqView isn't loaded and otherwise
  4768.       returns the current partition number from 1 to 199.
  4769.             Values: 0 to 199
  4770.             Manual reference: Section II.2
  4771.             Examples: BATUTIL [DV]
  4772.       ----------------------------------------------------------------------
  4773.       ECho            {}          Input: CM, BU       Output: DI
  4774.             Parameters: string to be echoed
  4775.             Echoes a string to the screen with metastring translation but no
  4776.       automatic CR/LF.  Colors determined by the AT and MN flags (defaulting
  4777.       to $1E on color and $07 on monochrome).  Can echo to STDOUT if the
  4778.       STdout command is used. PRetty gives more color control.
  4779.             Manual reference: Section III.3
  4780.             Examples: BATUTIL {EC hi there!}
  4781.             Internal parameters: AT, MN, ST, $T, ^T
  4782.             See also: FEcho, PRetty, FPretty, ATttribute, MNattribute,
  4783.                 STdout,BEcho
  4784.       ----------------------------------------------------------------------
  4785.       EDitenv         {}          Input: CM, SY, US   Output: EN
  4786.             Parameters: Optional Environment variable
  4787.             With no parameter, this command calls up a full screen listing of
  4788.       all variables in the environment with directions on how to edit
  4789.       them.  If a single word is given as a parameter, you can edit the
  4790.       string with that value if there is one or you can enter the value
  4791.       of a new variable. Lengths are limited to 255 bytes (rather than
  4792.       DOS' 127)
  4793.             Manual reference: Section V.9
  4794.             Examples: BATUTIL {ED prompt}
  4795.             Internal parameters: NBeep
  4796.             See also: SEt, PAthedit, NBeep
  4797.       ----------------------------------------------------------------------
  4798.  
  4799.  
  4800.     Chapter VII:COMMAND REFERENCE                              Page 89
  4801.  
  4802.  
  4803.  
  4804.  
  4805.                   Documentation for BATUTIL, Version 1.0 
  4806.  
  4807.  
  4808.       ENvrep          {}          Input: SY           Output: DI
  4809.             Parameters: None
  4810.             Gives a report on the screen of the total size and free space of
  4811.       the environment, its location in memory and a listing of all strings
  4812.       with their lengths.
  4813.             Manual reference: Section V.2
  4814.             Examples: BATUTIL {EN}
  4815.       ----------------------------------------------------------------------
  4816.       EOline          {}          Input: CM           Output: DI
  4817.             Parameters: None or +
  4818.             {EO} erases to the end of the line in the current attributes as
  4819.       set with AT or MN; {EO +} erase the entire line.  {EO} does not change
  4820.       the cursor position; {EO +} moves the cursor to column 1.
  4821.             Manual reference: Section III.3
  4822.             Examples: BATUTIL {RO -5}{EO +}{CO 5}{EC hi}
  4823.             Internal parameters: AT, MN
  4824.             See also: ATtribute, MNattribute, CLs
  4825.       ----------------------------------------------------------------------
  4826.       ERrorlevel      []/{}       Input: CM           Output: EL
  4827.             Parameters: Decimal number or Hex number preceded by $$ or
  4828.       $x(environmental variable)
  4829.             This allows the setting of errorlevel to a given number.
  4830.             Values: 0 to 199
  4831.             Manual reference: Section II.9
  4832.             Examples: BATUTIL {EC Yes or No?}{GE Y N}{EC $_Thanks!}{ER $(RC)}
  4833.             See also: RUn
  4834.       ----------------------------------------------------------------------
  4835.       EXist           []/{}       Input: CM,SY        Output: EL, EN
  4836.             Parameters: A single filename without wildcards
  4837.             A powerful extension of DOS' "if exist".  If filename has no path
  4838.       or drive, the possible responses are 0 = file exists in default
  4839.       directory; 1 = file exists on path (directory will be given in FDIR;
  4840.       see FDIR below); 2 = file doesn't exist on path.  If the filename has a
  4841.       drive or path responses are 0 = file exists; 2 = file does not exist; 9
  4842.       = path invalid.  Possible errors in 23x range - see chapter VIII.
  4843.       If the 'file' is a device then FDIR is set to IS_A_DEVICE.
  4844.             Values: 0,1,2,9
  4845.             Manual reference: Section II.6
  4846.             Examples: BATUTIL {EX autoexec.bat}
  4847.             Internal parameters: FDIR
  4848.             See also: FDir, CHeck, NUmberfiles, MAke, TOdayfile
  4849.       ----------------------------------------------------------------------
  4850.  
  4851.  
  4852.  
  4853.  
  4854.     Chapter VII:COMMAND REFERENCE                              Page 90
  4855.  
  4856.  
  4857.  
  4858.  
  4859.                   Documentation for BATUTIL, Version 1.0 
  4860.  
  4861.  
  4862.       FDir            {}          Input: CM           Output: IN
  4863.             Parameters: Variable name with leading \ treated specially
  4864.             By default if {EX ...} finds a file in the path but not in the
  4865.       default directory, then the directory of the file is stored in the
  4866.       environmental variable FDIR.  Similarly, a choice made by the user in a
  4867.       $f will place the path in the environmental variable FDIR.  {FD}
  4868.       with no parameter will suppress and {FD varname} will place it in
  4869.       the variable varname.  If varname starts with \ a trailing
  4870.       backspace is added to the path.
  4871.             Manual reference: Section II.6
  4872.             Examples: BATUTIL {FD \PATH}{EX command.com}
  4873.             See also: EXist, $f
  4874.       ----------------------------------------------------------------------
  4875.       FEcho           {}          Input: CM, FI       Output: DI
  4876.             Parameters: filename and optional label
  4877.             {FE filename label} finds the file "filename" and searches
  4878.       for a line ":label".  It then echoes each line between that label
  4879.       and the next line starting with ":".  Full metastring translation
  4880.       takes place.  A CR/LF is echoed for each line in the file except
  4881.       for the last.
  4882.             Manual reference: Sections III.5, I.5
  4883.             Examples: BATUTIL {FE %0 foo}
  4884.             Internal parameters: AT, MN, $T, ^T
  4885.             See also: ECho, PRetty, FPretty, ATttribute, MNattribute
  4886.       ----------------------------------------------------------------------
  4887.       FKey            {}          Input: None         Output: IN
  4888.             Parameters: None
  4889.             When used before a MEnu or FMenu command, if there are 9 or fewer
  4890.       menu items, this command turns on display of F1, F2, etc to the left of
  4891.       the menu list and the function and number keys make choices
  4892.             Manual reference: Section IV.3
  4893.             Examples: BATUTIL {FK}{FM %0 menulist}
  4894.             See also: MEnu, FMenu
  4895.       ----------------------------------------------------------------------
  4896.  
  4897.  
  4898.  
  4899.  
  4900.  
  4901.  
  4902.  
  4903.  
  4904.  
  4905.  
  4906.  
  4907.  
  4908.     Chapter VII:COMMAND REFERENCE                              Page 91
  4909.  
  4910.  
  4911.  
  4912.  
  4913.                   Documentation for BATUTIL, Version 1.0 
  4914.  
  4915.  
  4916.       FMenu           []/{}       Input: CM,FI,BU,US  Output: EL
  4917.             Parameters: filename and optional label
  4918.             {FM filename label} finds the file "filename" and searches
  4919.       for a line ":label".  It then processes each line between that
  4920.       label and the next line starting with ":".  The input lines up to
  4921.       one beginning with @ are treated as menu items; lines after a @ are
  4922.       treated as help text.
  4923.             Manual reference: Sections IV.2, I.5
  4924.             Examples: BATUTIL [FM %0 menulist]
  4925.             Internal parameters: NMouse, MHeader, POp, SHadow, FKey
  4926.             See also: MEnu, NMouse, MHeader, POp, SHadow, FKey
  4927.       ----------------------------------------------------------------------
  4928.       FPretty         {}          Input: CM, FI       Output: DI
  4929.             Parameters: filename and optional label
  4930.             {FP filename label} finds the file "filename" and searches
  4931.       for a line ":label".  It then echoes each line between that label
  4932.       and the next line starting with ":".  The initial attributes are
  4933.       determined by AT and MN but they can by changed by using @ followed
  4934.       immediately by a hex attribute. Full metastring translation takes
  4935.       place.  A CR/LF is echoed for each line in the file except for the
  4936.       last. Attributes reset to AT/MN for each new line.
  4937.             Manual reference: Sections III.5, I.5
  4938.             Examples: BATUTIL {FP %0 foo}
  4939.             Internal parameters: AT, MN
  4940.             See also: ECho, FEcho, FPretty, ATttribute, MNattribute
  4941.       ----------------------------------------------------------------------
  4942.       GEtkey          []/{}       Input: CM, US       Output: EL
  4943.             Parameters: List of keys as found in Section IV.4.  First
  4944.       parameter may be WAnnn or WAEnnn and final one may be BEep or ELse
  4945.             GEtkey waits for a keystroke from the user from a list supplied
  4946.       with the command and returns the number of the choice in the
  4947.       errorlevel.  The choice is echoed on the screen.  If the final "key" is
  4948.       BEep, the user is beeped for incorrect choices; if it is ELse, an
  4949.       incorrect choice causes an exit.  WAit and WAit with Echo will exit
  4950.       after a period with errorlevel set to 0
  4951.             Values: 0 to 64
  4952.             Manual reference: Sections IV.4, IV.5
  4953.             Examples: BATUTIL {GE Y N}
  4954.             Internal parameters: NFlush, CSent, VIsual
  4955.             See also: MEnu, NFlush, CSent, VIsual
  4956.       ----------------------------------------------------------------------
  4957.  
  4958.  
  4959.  
  4960.  
  4961.  
  4962.     Chapter VII:COMMAND REFERENCE                              Page 92
  4963.  
  4964.  
  4965.  
  4966.  
  4967.                   Documentation for BATUTIL, Version 1.0 
  4968.  
  4969.  
  4970.       HAltif          {}          Input: CM           Output: EL, IN
  4971.             Parameters: (~) string1 compare string2
  4972.                where compare is one of = (or $q), $l or $g
  4973.             Strings1 and 2 as well as the comparison undergo metastring
  4974.       translation.  If both strings can be evaluated as numbers up to
  4975.       134217727 in absolute value, then the comparison is made as
  4976.       numbers, otherwise as strings.  If the comparison is valid (or if ~
  4977.       followed by space is the first parameter), then BATUTIL exits with
  4978.       an errorlevel of 254.  Otherwise, the remainder of the command
  4979.       line is processed.
  4980.             Values: 254
  4981.             Manual reference: Section I.8
  4982.             Examples: BATUTIL {CA}{HA ~ $x(RC)=0}{EC You are not running
  4983.                                             Carousel}
  4984.                       BATUTIL {HA $H$l12}{EC It's before noon}
  4985.       ----------------------------------------------------------------------
  4986.       HImem           []/{}       Input: None         Output: EL
  4987.             Parameters: None
  4988.             Returns 0 if no XMS (Himem) driver is loaded and 1 if one is
  4989.       loaded
  4990.             Values: 0 or 1
  4991.             Manual reference: Section II.3
  4992.             Examples: BATUTIL [HI]
  4993.       ----------------------------------------------------------------------
  4994.       HOur            []/{}       Input: None         Output: EL
  4995.             Parameters: None
  4996.             Returns the hour of the day in military time from 0 to 23
  4997.             Values: 0 to 23
  4998.             Manual reference: Section II.2
  4999.             Examples: BATUTIL [HO]
  5000.             See also: DAte, MInute, WEekday, MOnth, YEar
  5001.       ----------------------------------------------------------------------
  5002.       KIllenv         {}          Input: CM           Output: EN
  5003.             Parameters: List of environment variables
  5004.             Removes all strings from the environment except for COMSPEC and
  5005.       any variables explicitly listed after {KI}
  5006.             Manual reference: Section V.6
  5007.             Examples: BATUTIL {SA present.env}{KI path}
  5008.             See also: SAvenv, LOadenv
  5009.       ----------------------------------------------------------------------
  5010.  
  5011.  
  5012.  
  5013.  
  5014.  
  5015.  
  5016.     Chapter VII:COMMAND REFERENCE                              Page 93
  5017.  
  5018.  
  5019.  
  5020.  
  5021.                   Documentation for BATUTIL, Version 1.0 
  5022.  
  5023.  
  5024.       LEngth          []/{}       Input: CM           Output: EL
  5025.             Parameters: string with metastring translation
  5026.             Returns the length of the string given so {LE $x(foo)} would
  5027.       return the length of the environmental variable foo.
  5028.             Values: 0 to 199
  5029.             Manual reference: Section V.4
  5030.             Examples: BATUTIL [LE $x(name)]
  5031.       ----------------------------------------------------------------------
  5032.       LIm             []/{}       Input: None         Output: EL
  5033.             Parameters: None
  5034.             Returns 0 if no EMS driver is found and otherwise 10 times the
  5035.       LIM version.
  5036.             Values: Various - most common are 0, 32, 40
  5037.             Manual reference: Section II.3
  5038.             Examples: BATUTIL [LI]
  5039.       ----------------------------------------------------------------------
  5040.       LOadenv         {}          Input: CM           Output: EN
  5041.             Parameters: Filename or Filename /m
  5042.             Finds the file given (looks on path if need be) and if found
  5043.       either replaces the environment with the content of the file or if the
  5044.       /m parameter is included merges it with the environment.  No action
  5045.       taken if the file is not appropriate (ASCII with an equal sign on each
  5046.       line and all caps prior to the equal sign).
  5047.             Manual reference: Section V.6
  5048.             Examples: BATUTIL {LO present.env}
  5049.             See also: KIllenv, SAvenv
  5050.       ----------------------------------------------------------------------
  5051.       MAke            []/{}       Input: CM, SY       Output: EL
  5052.             Parameters: A pair of filenames
  5053.             Intended for a homebrewed UNIX type MAKE utility this takes two
  5054.       filenames and returns codes as follows:
  5055.             0 = file2 not found
  5056.             1 = file2 is strictly older
  5057.             2 = file1 not found
  5058.             3 = file1 older or the same age as file2
  5059.             9 = path not found
  5060.             Values: 0,1,2,3,9
  5061.             Manual reference: Section II.8
  5062.             Examples: BATUTIL [MA foobar.pas foobar.exe]
  5063.             See also: EXist, TOdayfile
  5064.       ----------------------------------------------------------------------
  5065.  
  5066.  
  5067.  
  5068.  
  5069.  
  5070.     Chapter VII:COMMAND REFERENCE                              Page 94
  5071.  
  5072.  
  5073.  
  5074.  
  5075.                   Documentation for BATUTIL, Version 1.0 
  5076.  
  5077.  
  5078.       MEnu            []/{}       Input: CM, BU, US   Output: EL
  5079.             Parameters: List of choices separated by spaces
  5080.             Makes a menu with choices given by the list of parameters
  5081.       following the ME command.  The number of the user's choice is returned
  5082.       in the errorlevel.  Capital letters used for speed choices.
  5083.             Manual reference: Sections IV.1,3
  5084.             Examples: BATUTIL [ME Copy Erase Rename eXit]
  5085.             Internal parameters: NMouse, MHeader, POp, SHadow, FKey
  5086.             See also: FMenu, NMouse, MHeader, POp, SHadow, FKey
  5087.       ----------------------------------------------------------------------
  5088.       MHeader         {}          Input: CM           Output: IN
  5089.             Parameters: String
  5090.             Allows you to specify a header to appear at top of a menu
  5091.       prepared with a subsequent MEnu or FMenu command (on the same BATUTIL
  5092.       command line ).  Metastring translation is done.
  5093.             Manual reference: Section IV.3
  5094.             Examples: BATUTIL {MH My menu: $E}[ME Copy Erase Rename eXit]
  5095.             See also: FMenu, MEnu
  5096.       ----------------------------------------------------------------------
  5097.       MInute          []/{}       Input: None         Output: EL
  5098.             Parameters: None
  5099.             Returns the minute of the hour from 0 to 59
  5100.             Values: 0 to 59
  5101.             Manual reference: Section II.2
  5102.             Examples: BATUTIL [MI]
  5103.             See also: DAte, HOur, WEekday, MOnth, YEar
  5104.       ----------------------------------------------------------------------
  5105.       MNattribute     {}          Input: CM           Output: IN
  5106.             Parameters: Hex number from 0 to FF with optional leading $
  5107.             BATUTIL keeps an internal attribute used when EChoing, for
  5108.       shadows in MEnus, when the CLs command clears the screen,for the $?
  5109.       command.  Separate attributes are keep for graphics and monochrome
  5110.       screens. It defaults to $07 (normal).  The {MN xx} changes it.  See
  5111.       section III.3 for a list of attributes. Two special values do not have
  5112.       their default meaning: $55 uses the attribute at the cursor at the time
  5113.       that ECho is called; $66 write with no change in the underlying
  5114.       attributes.
  5115.             Manual reference: Section III.3
  5116.             Examples: BATUTIL {EC hello$S}{MN $70}{EC there}   would echo
  5117.       "hello " in normal and "there" in reverse video
  5118.             See also: ATtribute, ECho, PRetty, CLs, EOline
  5119.       ----------------------------------------------------------------------
  5120.  
  5121.  
  5122.  
  5123.  
  5124.     Chapter VII:COMMAND REFERENCE                              Page 95
  5125.  
  5126.  
  5127.  
  5128.  
  5129.                   Documentation for BATUTIL, Version 1.0 
  5130.  
  5131.  
  5132.       MOnth           []/{}       Input: None         Output: EL
  5133.             Parameters: None
  5134.             Returns the month of the year from 1 to 12
  5135.             Values: 1 to 12
  5136.             Manual reference: Section II.2
  5137.             Examples: BATUTIL [MO]
  5138.             See also: DAte, HOur, WEekday, MInute, YEar
  5139.       ----------------------------------------------------------------------
  5140.       NBeep           {}          Input: None         Output: IN
  5141.             Parameters: None
  5142.             Suppresses beeps in the EDitenv and PAthedit commands
  5143.             Manual reference: Section V.8
  5144.             Examples: BATUTIL {NB}{ED}
  5145.             See also: EDitenv, PAthedit
  5146.       ----------------------------------------------------------------------
  5147.       NFlush          {}          Input: None         Output: IN
  5148.             Parameters: None
  5149.             The keyboard is flushed before user input is gotten for the
  5150.       GEtkey and USername commands; NFlush will tell the next call to either
  5151.       of these to not flush the keyboard allowing STACKEY input or prior user
  5152.       input.  The internal flag is reset by such a call.
  5153.             Manual reference: Section IV.5
  5154.             Examples: BATUTIL {NF}{GE Y N}{GE Y N}  ; the first call
  5155.       would not flush the buffer; the second would.
  5156.             See also: GEtkey, USername
  5157.       ----------------------------------------------------------------------
  5158.       NMouse          {}          Input: None         Output: IN
  5159.             Parameters: None
  5160.             MEnu and FMenu allow the use of a Microsoft compatible mouse
  5161.       if present.  NMouse will suppress the use of a mouse. The internal
  5162.       flag is reset by such a call.
  5163.             Manual reference: Section IV.1
  5164.             Examples: BATUTIL {NM}[ME Copy Erase Rename eXit]
  5165.             See also: MEnu, FMenu
  5166.       ----------------------------------------------------------------------
  5167.       NSound          {}          Input: None         Output: IN
  5168.             Parameters: None
  5169.             The sound command will be suppressed if this parameter is
  5170.       set.  Only makes sense if used as part of an BU@ environment
  5171.       string.
  5172.             Manual reference: Section III.9
  5173.             Examples: set BU@={NS}
  5174.             See also: SOund
  5175.       ----------------------------------------------------------------------
  5176.  
  5177.  
  5178.     Chapter VII:COMMAND REFERENCE                              Page 96
  5179.  
  5180.  
  5181.  
  5182.  
  5183.                   Documentation for BATUTIL, Version 1.0 
  5184.  
  5185.  
  5186.       NUmberfiles     []/{}       Input: CM, SY       Output: EL
  5187.             Parameters: filespec(s) with path and wildcards allowed.
  5188.             Returns the total number of files found matching one of the given
  5189.       filespecs up to 199
  5190.             Values: 0 to 199
  5191.             Manual reference: Section II.6
  5192.             Examples: BATUTIL {NU C:\bin\*.com C:\bin\*.exe}
  5193.             See also: EXist, CHeck
  5194.       ----------------------------------------------------------------------
  5195.       OView           []/{}       Input: SY           Output: EL
  5196.             Parameters: None
  5197.             OView is special to Sunny Hill's OMNIVIEW multitasking
  5198.       software.  It returns 0 is OmniView isn't loaded and otherwise
  5199.       returns the current partition number from 1 to 10.   In versions
  5200.       current at the time this manual is written, the partition is
  5201.       numbered up to 10 but if it increased, this should still work
  5202.             Values: 0 to 10
  5203.             Manual reference: Section II.2
  5204.             Examples: BATUTIL [OV]
  5205.       ----------------------------------------------------------------------
  5206.       P  Pause mode      Initial Parameter            Output:  IN
  5207.             Parameters: None
  5208.             If the first parameter on the command line or in BU@ is P (or
  5209.       p), then Pause mode is turned on and messages are displayed when
  5210.       BATUTIL exits with an error and processing is halted until you hit
  5211.       a key.
  5212.             Manual reference: I.3
  5213.             Examples: BATUTIL P {ec $A}
  5214.       ----------------------------------------------------------------------
  5215.       PAthedit        {}          Input: SY, US       Output: EN
  5216.             Parameters: None
  5217.             Calls up an interactive editor to edit the path
  5218.             Manual reference: Section V.8
  5219.             Examples: BATUTIL {PA}
  5220.             Internal parameters: NBeep
  5221.             See also: EDitenv, NBeep, ADdpath, DElpath
  5222.       ----------------------------------------------------------------------
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.     Chapter VII:COMMAND REFERENCE                              Page 97
  5233.  
  5234.  
  5235.  
  5236.  
  5237.                   Documentation for BATUTIL, Version 1.0 
  5238.  
  5239.  
  5240.       PMatch          []/{}       Input: CM           Output: EL
  5241.             Parameters: List of words
  5242.             If the words are labelled word0, word1, ... , this command will
  5243.       try to match word0 to word1,....  If there is no match the
  5244.       errorlevel is set to 0; otherwise to number of the first match
  5245.       found.  Intended to check batch file parameters.  By default not
  5246.       case sensitive.
  5247.             Values: 0 to 64
  5248.             Manual reference: Section IV.7
  5249.             Examples: BATUTIL {PM %1 bold compressed underline}
  5250.             Internal parameters: CSent
  5251.             See also: CSent
  5252.       ----------------------------------------------------------------------
  5253.       POp             {}          Input: CM           Output: IN
  5254.             Parameters: None or +
  5255.             By default, menus just appear on the screen.  {PO} will cause
  5256.       them to appear with a visual explosion and {PO +} with a visual
  5257.       explosion and a popping sound.  The visual/sound effects occur also
  5258.       when the menu pops down.  The internal flag is reset by such a call.
  5259.             Manual reference: Section IV.3
  5260.             Examples: BATUTIL {PO +}[FM %0 menulist]
  5261.             See also: MEnu, FMenu
  5262.       ----------------------------------------------------------------------
  5263.       PRetty          {}          Input: CM           Output: DI
  5264.             Parameters: String to display with embedded @ commands
  5265.             Like ECho, this will display a string but with a change in
  5266.       attribute possible in mid-string by inserting @ followed by the hex
  5267.       attribute number.
  5268.             Manual reference: Section III.4
  5269.             Examples: BATUTIL {PR @1FH@1Ei}
  5270.             Internal parameters: AT, MN
  5271.             See also: ECho, FEcho, FPretty, ATttribute, MNattribute
  5272.       ----------------------------------------------------------------------
  5273.       QLock           []/{}       Input: CM, SY       Output: EL, SY
  5274.             Parameters: First parameter one of C,N,S,I; second optional +/-
  5275.             Returns errorlevel based on the states of one of CapsLock,
  5276.       Numlock, ScrollLock, Insert mode.  Optional turns off (-) or on (+)
  5277.             Values: 0 = off, 1 = on
  5278.             Manual reference: Section IV.9
  5279.             Examples: BATUTIL [C -] will test Capslock and turn it off
  5280.       ----------------------------------------------------------------------
  5281.  
  5282.  
  5283.  
  5284.  
  5285.  
  5286.     Chapter VII:COMMAND REFERENCE                              Page 98
  5287.  
  5288.  
  5289.  
  5290.  
  5291.                   Documentation for BATUTIL, Version 1.0 
  5292.  
  5293.  
  5294.       QUery           {}          Input: CM           Output: IN
  5295.             Parameters: - or +
  5296.             {QU -} sets an internal flag turning off translation of $Q and $?
  5297.       metastrings in the set command.  {QU +} undoes the effect of {QU -}.
  5298.       BATUTIL does not keep internal flags from one running to the next so
  5299.       $Q, $? translation is turned back on for each new loading.
  5300.             Manual reference: Section V.4
  5301.             Examples: BATUTIL {QU-}{set foo1=$Q}{QU +}{set foo2=$Q}
  5302.               would set foo1 to $Q and foo2 to a user entered string.
  5303.             See also: $Translates, ^Translate, $Q/$?
  5304.       ----------------------------------------------------------------------
  5305.       REm             {}          Input: None         Output: None
  5306.             Parameters: None
  5307.             Allows placing of remarks in a BATUTIL command line
  5308.             Examples: BATUTIL {AT $4E}{CL}{RE clears screen in red!}
  5309.       ----------------------------------------------------------------------
  5310.       ROw             {}          Input: CM           Output: DI
  5311.             Parameters: One decimal number with optional +, - or T in front;
  5312.       decimal number must be between 1 and 25.
  5313.             Moves the cursor; if just a number is given the cursor is moved
  5314.       to precisely that row.  If a plus or minus precedes the number,
  5315.       then the movement is relative to the current position but wrapping
  5316.       does not take place at the screen top.  Scrolling will take place
  5317.       at the screen bottom.  {RO Txx} sets the location of where the
  5318.       countdown clock will occur with {GEtkey WAit}.
  5319.             Manual reference: Section III.7, Section IV.5
  5320.             Examples: BATUTIL {CL}{RO 5}{EC This line is line 5}
  5321.                       BATUTIL {RO 1}{EC Time Left:}{RO T1}{CO T12}{GE WA60}
  5322.             See also: COl, CUrsor
  5323.       ----------------------------------------------------------------------
  5324.       RUn             []/{}       Input: CM           Output: EL
  5325.             Parameters: Program name and parameters
  5326.             This will search the path for the program in question, run it and
  5327.       return the errorlevel.  Generally better to run WHATEL which takes less
  5328.       memory away from the program being run.
  5329.             Values: 0 to 255
  5330.             Manual reference: Section II.7
  5331.             Examples: BATUTIL [RU programname]
  5332.       ----------------------------------------------------------------------
  5333.  
  5334.  
  5335.  
  5336.  
  5337.  
  5338.  
  5339.  
  5340.     Chapter VII:COMMAND REFERENCE                              Page 99
  5341.  
  5342.  
  5343.  
  5344.  
  5345.                   Documentation for BATUTIL, Version 1.0 
  5346.  
  5347.  
  5348.       SAvenv          {}          Input: CM           Output: EN
  5349.             Parameters: Filename
  5350.             Saves the current environment to an ASCII file in the form
  5351.               VARNANE=var_value
  5352.       one variable per line.  Errorlevel set to 199 if the filename
  5353.       exists and user doesn't allow the file to be overwritten
  5354.             Manual reference: Section V.6
  5355.             Examples: BATUTIL {SA present.env}
  5356.             See also: KIllenv, LOadenv
  5357.       ----------------------------------------------------------------------
  5358.       SCanread        []/{}       Input: US           Output: EL
  5359.             Parameters: None
  5360.  
  5361.             Waits for a keystroke and reports the "Scancode" part of the
  5362.       int 16H value for the keystruck.
  5363.             Values: 0 to 199
  5364.             Manual reference: Section IV.6
  5365.             Examples: BATUTIL [SC]
  5366.             Internal parameters: NFlush (determines whether the keyboard is
  5367.       flushed)
  5368.             See also: ASciiread, GEtkey, NFlush
  5369.       ----------------------------------------------------------------------
  5370.       SEt             {}          Input: CM           Output: EN
  5371.             Parameters: One or more of the form varname=varvalue
  5372.             SE allows you to place variables in the active DOS environment.
  5373.       Metastring translation takes place including $x, $f, $Q/$?
  5374.             Manual reference: Sections V.3,4,5
  5375.             Examples: BATUTIL {ec Enter filespec}{set ab=$Q file=$f($x(ab))}
  5376.             Internal parameters: $Translate, ^Translate, QUery
  5377.             See also: $f, $x, $Q/$?, $Translate, ^Translate, QUery
  5378.       ----------------------------------------------------------------------
  5379.       SHadow          {}          Input: None         Output: IN
  5380.             Parameters: None
  5381.             By default, menus just appear on the screen.  {SH} will cause
  5382.       them to appear with shadow in the current colors as set by AT/MN.
  5383.       The internal flag is reset by such a call.
  5384.             Manual reference: Section IV.3
  5385.             Examples: BATUTIL {SH}[FM %0 menulist]
  5386.             Internal parameters: AT, MN
  5387.             See also: MEnu, FMenu
  5388.       ----------------------------------------------------------------------
  5389.  
  5390.  
  5391.  
  5392.  
  5393.  
  5394.     Chapter VII:COMMAND REFERENCE                             Page 100
  5395.  
  5396.  
  5397.  
  5398.  
  5399.                   Documentation for BATUTIL, Version 1.0 
  5400.  
  5401.  
  5402.       SOund           {}          Input: CM           Output: DI
  5403.             Parameters: Sound number from 1 to 20; optional repeat count
  5404.             Makes one of 20 sounds; 1 to 10 are small sounds, 11 to 20 are
  5405.       tunes.
  5406.             Manual reference: Section III.9
  5407.             Examples: BATUTIL {SO 18}
  5408.             Internal parameters: NSound
  5409.             See also: NSound
  5410.       ----------------------------------------------------------------------
  5411.       STdout          {}          Input: CM           Output: IN
  5412.             Parameters: - or optional +
  5413.             {ST +} (equivalent to {ST}) will direct output from the BATUTIL
  5414.       {ECho} command to standard output which can redirected.  {ST -} will
  5415.       return to the default behavior of writing ECho output directly to
  5416.       the screen in colors set with AT/MN.
  5417.             Manual reference: Section III.8
  5418.             Examples: BATUTIL {ST}{EC ^G}{ST -}{EC You dummy!!!}
  5419.             See also: ECho
  5420.       ----------------------------------------------------------------------
  5421.       TOdayfile       []/{}       Input: CM, SY       Output: EL
  5422.             Parameters: Filename without wildcards; optional hour
  5423.             {TO filename} will search for the file specified and check its
  5424.       date against today's date and return the following:
  5425.             0 = the file has today's date
  5426.             1 = the file exists and doesn't have today's date
  5427.             2 = file not found           9 = invalid path
  5428.       If two parameters are given, the first must be a number from 0 to
  5429.       23. Then, "today" and the file date/time will be compared assuming
  5430.       days start at the hour in the first parameter.
  5431.             Values: 0,1,2,9
  5432.             Manual reference: Section II.8
  5433.             Examples: BATUTIL {TO test.txt}
  5434.                       BATUTIL {TO 5 test.txt}
  5435.             See also: EXist, MAke
  5436.       ----------------------------------------------------------------------
  5437.  
  5438.  
  5439.  
  5440.  
  5441.  
  5442.  
  5443.  
  5444.  
  5445.  
  5446.  
  5447.  
  5448.     Chapter VII:COMMAND REFERENCE                             Page 101
  5449.  
  5450.  
  5451.  
  5452.  
  5453.                   Documentation for BATUTIL, Version 1.0 
  5454.  
  5455.  
  5456.       USername        []/{}       Input: CM, US       Output: EL
  5457.             Parameters: sequence of names; first one can be a number of
  5458.               tries; second can be *
  5459.             In its simplest form, a sequence of words are given following
  5460.       {US.  The user types in a "username" and BATUTIL responds which number
  5461.       in the list was matched and 0 if the string did not match.  If a number
  5462.       is given as the first parameter, the user will have additional chances
  5463.       and the remaining parameters are labelled 1,2,.. and the same rules
  5464.       apply.  If the second parameter is *, the same rules apply (with the
  5465.       third parameter now as choice 1) BUT the system is halted if no correct
  5466.       choice is given.
  5467.             Values: 0 to 64
  5468.             Manual reference: Section IV.7
  5469.             Examples: BATUTIL
  5470.             Internal parameters: CSent
  5471.             See also: CSent
  5472.       ----------------------------------------------------------------------
  5473.       V  Verbose mode    Initial Parameter            Output:  IN
  5474.             Parameters: None
  5475.             If the first parameter on the command line or in BU@ is V (or v),
  5476.       then Verbose mode is turned on and messages are displayed when BATUTIL
  5477.       exits with an error.
  5478.             Manual reference: I.3
  5479.             Examples: BATUTIL V {ec $A}
  5480.       ----------------------------------------------------------------------
  5481.       VIsual          {}          Input: CM           Output: IN
  5482.             Parameters:  A,1,N,D,DA,D1,DN
  5483.             Determines the degree of visual feedback from the GEtkey command.
  5484.       The default is to have matching choices echoed including #nnn and two
  5485.       letter abbreviations.  A will have incorrect choices echoed in the form
  5486.       letter? or ¿? for keys without ASCII codes.  1 will restrict echoes only
  5487.       to single ASCII codes and N will suppress echos.  By default, the cursor
  5488.       moves on space after a GEtkey - D suppresses
  5489.       that space.
  5490.             Manual reference: Section IV.5
  5491.             Examples: BATUTIL {VI DA}{EC Choose a key}{GE Y N}
  5492.             See also: GEtkey
  5493.       ----------------------------------------------------------------------
  5494.  
  5495.  
  5496.  
  5497.  
  5498.  
  5499.  
  5500.  
  5501.  
  5502.     Chapter VII:COMMAND REFERENCE                             Page 102
  5503.  
  5504.  
  5505.  
  5506.  
  5507.                   Documentation for BATUTIL, Version 1.0 
  5508.  
  5509.  
  5510.       WEekday         []/{}       Input: None         Output: EL
  5511.             Parameters: None
  5512.             Returns the day of the week from 0 = Sunday to 6 = Saturday
  5513.             Values: 0 to 6
  5514.             Manual reference: Section II.2
  5515.             Examples: BATUTIL [WE]
  5516.             See also: DAte, HOur, MOnth, MInute, YEar
  5517.       ----------------------------------------------------------------------
  5518.       Year            []/{}       Input: None         Output: EL
  5519.             Parameters: None
  5520.             Returns the year since 1980 (i.e. 0 = 1980, 10 = 1990)
  5521.             Values: 0 to 19
  5522.             Manual reference: Section II.2
  5523.             Examples: BATUTIL [YE]
  5524.             See also: DAte, HOur, WEekday, MInute, MOnth
  5525.       ----------------------------------------------------------------------
  5526.  
  5527.  
  5528.  
  5529.  
  5530.  
  5531.  
  5532.  
  5533.  
  5534.  
  5535.  
  5536.  
  5537.  
  5538.  
  5539.  
  5540.  
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.     Chapter VII:COMMAND REFERENCE                             Page 103
  5557.  
  5558.  
  5559.  
  5560.  
  5561.                           Chapter VIII:ERROR MESSAGES
  5562.  
  5563.       VIII.1 Fatal Errors
  5564.  
  5565.             There are certain errors that you may make in syntax or
  5566.       problems with your trying to place something in the environment for
  5567.       which there isn't room where BATUTIL cannot recover or where it cannot
  5568.       figure out the action you'd want it to take.  There may also be
  5569.       situations where what we think is the environment doesn't seem right
  5570.       and BATUTIL would then want you to contact us and inform us of what has
  5571.       happened.  In all these situations BATUTIL exits.  One action it does
  5572.       to indicate such a fatal error is to exit with the DOS errorlevel
  5573.       set to a number between 200 and 253.  Only the AScii command and
  5574.       the RUn command can return errorlevels in this range without
  5575.       indicating an error.  Errorlevel 254 is reserved for the HAltif
  5576.       command and errorlevel 255 for ^Break exits.  All other commands
  5577.       set an errorlevel in the range 0 to 199.
  5578.  
  5579.             While debugging a BATUTIL script, you can use either VERBOSE or
  5580.       PAUSE mode.  The verbose mode is the default and can be turned off by
  5581.       using a Q (not in brackets) as the first non blank character on the
  5582.       BATUTIL command line or in the BU@ environmental variable.  Pause mode
  5583.       can be turneed on similarly except that P is used in place of V.  See
  5584.       Section I.3 for further discussion.
  5585.  
  5586.  
  5587.       VIII.2 List of Error Codes
  5588.  
  5589.       200: Not a BATUTIL command
  5590.       201: Does not effect errorlevel; use {} not [ ]
  5591.       202: Incorrect placement of [,],{ or }
  5592.       204: Some of the required parameters are missing
  5593.       205: Too many parameters
  5594.       206: Number expected
  5595.       207: Number out of allowed range
  5596.       208: Illegal value for parameter
  5597.       209: Metastring syntax error
  5598.       210: Only one #I/@I command allowed per command line
  5599.       211: Unable to locate DOS environment
  5600.       212: Environment corrupted or not found
  5601.       213: Internal error in environment handling
  5602.       215: Too many variables in environment
  5603.       216: Environmental variable too large
  5604.       217: Environment too small for attempted change
  5605.       220: SAVENV error: path not found
  5606.       221: SAVENV/LOADENV error: file access error
  5607.       222: LOADENV error: file not found
  5608.  
  5609.  
  5610.     Chapter VIII:ERROR MESSAGES                               Page 104
  5611.  
  5612.  
  5613.  
  5614.  
  5615.                   Documentation for BATUTIL, Version 1.0 
  5616.  
  5617.  
  5618.       223: LOADENV error: invalid environment in file
  5619.       224: LOADENV error: Too large environment in file
  5620.       226: Invalid path variable in environment
  5621.       227: Proposed new path is too long
  5622.       230: Drive not ready
  5623.       231: Other DOS disk error
  5624.       232: DOS unable to access drive {DRIVE LETTER}
  5625.       235: RUN error: Program not found
  5626.       236: RUN error: Insufficient memory to run program
  5627.       237: RUN error: DOS error
  5628.       240: FECHO, FPRETTY, FMENU error: file not found
  5629.       241: FECHO, FPRETTY, FMENU error: label not found
  5630.       242: FECHO, FPRETTY, FMENU error: too many lines between labels
  5631.       243: FECHO, FPRETTY, FMENU error: no lines between labels
  5632.       245: Too many items in MENU or FMENU
  5633.       246: Improper FMENU lines
  5634.       250: HALTIF error: No comparison given
  5635.       253: Turbo Pascal Runtime Error!
  5636.  
  5637.  
  5638.        VIII.3 Explanation of Error Codes
  5639.  
  5640.       200: Not a BATUTIL command
  5641.                The first word inside each pair of {} or [] must be one of
  5642.       the BATUTIL commands or must be a valid truncation (have at least
  5643.       the first two letters and the remaining letters agree with a
  5644.       BATUTIL command).
  5645. ==========================================================================
  5646.       201: Does not effect errorlevel; use {} not [ ]
  5647.             Some BATUTIL commands set the errorlevel and may be placed
  5648.       inside [] (see section I.4).  You placed a command NOT of this
  5649.       type inside [].
  5650. ==========================================================================
  5651.       202: Incorrect placement of [,],{ or }
  5652.             BATUTIL was unable to parse the command line because of extra
  5653.       or missing brackets.  Here are some examples where you will get
  5654.       this error:
  5655.             BATUTIL {}
  5656.             BATUTIL {EC hi
  5657.             BATUTIL {EC hi{
  5658. ==========================================================================
  5659.       204: Some of the required parameters are missing
  5660.             The command requires more parameters than you have given or
  5661.       you may have given no parameters
  5662.  
  5663.  
  5664.     Chapter VIII:ERROR MESSAGES                               Page 105
  5665.  
  5666.  
  5667.  
  5668.  
  5669.                   Documentation for BATUTIL, Version 1.0 
  5670.  
  5671.  
  5672. ==========================================================================
  5673.       205: Too many parameters
  5674.             BATUTIL has found more parameters than it expected.  If you
  5675.       place a parameter with a space in it, you will often get this error
  5676.       since BATUTIL parses a space as a separator between parameters.  To
  5677.       place a space in most parameters, use $S
  5678. ==========================================================================
  5679.       206: Number expected
  5680.             There are certain place where BATUTIL expects a number, e.g.
  5681.       in {AT xx} where xx should be a number.  If there is not a number
  5682.       there, then you'll get this message, for example if you type
  5683.             BATUTIL {AT HI}
  5684. ==========================================================================
  5685.       207: Number out of allowed range
  5686.             In a command like {CO xx}, the parameter x must lie in the
  5687.       range 1 to 80 (unless proceeded by a + or -).  At least this is so
  5688.       if the screen is 80 columns wide.  You'll get this error if a
  5689.       number out of the allowed range is provided.
  5690. ==========================================================================
  5691.       208: Illegal value for parameter
  5692.             BATUTIL uses this to indicate some other error in the form of
  5693.       a parameter, e.g. {CU x} must have x equal to  + or - and you'll
  5694.       get this error if you use another value.  In some places, you'll
  5695.       get this error when error 205 might be more appropriate.
  5696. ==========================================================================
  5697.       209: Metastring syntax error
  5698.             BATUTIL found an error when trying to do metastring
  5699.       translation.  This most often happens when a $ or a ^ is followed
  5700.       by an illegal character.  To place an actual $ or ^ in a string
  5701.       (which can then be followed by anything) remember to use $$ or $^.
  5702. ==========================================================================
  5703.       210: Only one #I/@I command allowed per command line
  5704.             You cannot place both an @I and a #I command on the same
  5705.       command line nor are two calls to either allowed.
  5706. ==========================================================================
  5707.       211: Unable to locate DOS environment
  5708.             Please report this error to CTRLALT Associates.  Since
  5709.       BATUTIL will manipulate the true DOS environment, it is essential
  5710.       that it be found.  We believe that our method using undocumented
  5711.       information will always work but if BATUTIL cannot find what it is
  5712.       sure is the real environment, it will exit.
  5713. ==========================================================================
  5714.       212: Environment corrupted or not found
  5715.             Please report this error to CTRLALT Associates.  Since BATUTIL
  5716.  
  5717.  
  5718.     Chapter VIII:ERROR MESSAGES                               Page 106
  5719.  
  5720.  
  5721.  
  5722.  
  5723.                   Documentation for BATUTIL, Version 1.0 
  5724.  
  5725.  
  5726.       will manipulate the true DOS environment, it is essential that it be
  5727.       found.  We believe that our method using undocumented information will
  5728.       always work but if BATUTIL cannot find what it is sure is the real
  5729.       environment, it will exit.  This message indicates that BATUTIL found
  5730.       what it believes to be the DOS environment and it didn't have the
  5731.       proper form.  Either BATUTIL didn't find the true environment or your
  5732.       true environment is corrupted.  IMPORTANT NOTE: If you are using
  5733.       4DOS and get this error, only report it if you loaded 4DOS with the
  5734.       /M:xxx parameter.  BATUTIL is incompatible with versions of 4DOS
  5735.       prior to 2.1 or ones not loaded with /M.
  5736. ==========================================================================
  5737.       213: Internal error in environment handling
  5738.             Please report this error to CTRLALT Associates.  Since
  5739.       BATUTIL will manipulate the true DOS environment, it is essential
  5740.       that it be found.  We believe that our method using undocumented
  5741.       information will always work but if BATUTIL cannot find what it is
  5742.       sure is the real environment, it will exit.
  5743. ==========================================================================
  5744.       215: Too many variables in environment
  5745.             BATUTIL cannot handle environments with more than 510
  5746.       different strings in it.  If you have more than that many strings,
  5747.       let us know - we're curious what you could possibly have there!
  5748. ==========================================================================
  5749.       216: Environmental variable too large
  5750.             BATUTIL cannot handle environments where any string has more
  5751.       than 255 characters.  Normally, you shouldn't have any such strings
  5752.       since DOS only allows strings up to 127 characters and BATUTIL only
  5753.       up to 255.
  5754. ==========================================================================
  5755.       217: Environment too small for attempted change
  5756.             You tried, e.g. with a {SE  } command to place something in
  5757.       the environment for which there was insufficient room.
  5758. ==========================================================================
  5759.       220: SAVENV error: path not found
  5760.             The directory part of the filespec in
  5761.                  {SA filespec}
  5762.       was invalid.
  5763. ==========================================================================
  5764.       221: SAVENV/LOADENV error: file access error
  5765.             There was a disk or other error that prevented access to
  5766.       the file in question.  The most common cause of this will be a disk
  5767.       full or write protected disk during a SAVENV.  The error message
  5768.       displayed on the screen will give extra information (ignore the
  5769.       extra error number given)
  5770.  
  5771.  
  5772.     Chapter VIII:ERROR MESSAGES                               Page 107
  5773.  
  5774.  
  5775.  
  5776.  
  5777.                   Documentation for BATUTIL, Version 1.0 
  5778.  
  5779.  
  5780. ==========================================================================
  5781.       222: LOADENV error: file not found
  5782.             The file which you asked to have loaded into the environment
  5783.       could not be found.
  5784. ==========================================================================
  5785.       223: LOADENV error: invalid environment in file
  5786.             There was a line in the file you asked to have loaded into
  5787.       the environment or it did not have the form
  5788.             INCAPS=string
  5789.       on each line.  A file obtained with {SAvenv} should always load
  5790.       without this message.  If you get this message with a file saved
  5791.       with BATUTIL, please notify CTRLALT Associates.
  5792. ==========================================================================
  5793.       224: LOADENV error: Too large environment in file
  5794.             No room in the DOS environment for the file you tried to load
  5795. ==========================================================================
  5796.       226: Invalid path variable in environment
  5797.             In parsing the path for a {DElpath ...} or {ADdpath ...}
  5798.       command, BATUTIL found an invalid path.  Valid paths have strings
  5799.       without spaces separated by semicolons with an optional semicolon
  5800.       at the end.  DOS will accept invalid path strings with its PATH
  5801.       command.
  5802. ==========================================================================
  5803.       227: Proposed new path is too long
  5804.             BATUTIL limits environmental strings to 255 bytes each.  Your
  5805.       attempt to use {ADdpath ...} or {PAthedit} would have resulting in
  5806.       a path in excess of 255 characters and so it was not accomplished.
  5807. ==========================================================================
  5808.       230: Drive not ready
  5809.             DOS error - usually due to an open diskette drive door.
  5810. ==========================================================================
  5811.       231: Other DOS disk error
  5812.             DOS wouldn't allow access to the file and reported an error
  5813.       other than Drive not ready.
  5814. ==========================================================================
  5815.       232: DOS unable to access drive {DRIVE LETTER}
  5816.             Used by the #Disk and @Disk commands to indicate either error
  5817.       230 or 231.
  5818. ==========================================================================
  5819.       235: RUN error: Program not found
  5820.             The program name after a {RUn ...} command wasn't in the
  5821.       current directory or on the path (or in the directory name that you
  5822.       gave}.  RUn can only run EXE and COM programs and not batch files.
  5823. ==========================================================================
  5824.  
  5825.  
  5826.     Chapter VIII:ERROR MESSAGES                               Page 108
  5827.  
  5828.  
  5829.  
  5830.  
  5831.                   Documentation for BATUTIL, Version 1.0 
  5832.  
  5833.  
  5834.       236: RUN error: Insufficient memory to run program
  5835.             DOS reported insufficient free memory to run the program you
  5836.       asked to RUn
  5837. ==========================================================================
  5838.       237: RUN error: DOS error
  5839.             DOS reported an error when trying to run the program that you
  5840.       asked to RUn.  All these errors are unusual and you should report any
  5841.       such message to CTRLALT Associates together with the extra "special
  5842.       error number" which was reported.
  5843. ==========================================================================
  5844.       240: FECHO, FPRETTY, FMENU error: file not found
  5845.             In {FEcho filename label}, the file filename could not be
  5846.       found or similarly for FPretty or FMenu
  5847. ==========================================================================
  5848.       241: FECHO, FPRETTY, FMENU error: label not found
  5849.             In {FEcho filename label}, the label could not be found or
  5850.       similarly for FPretty or FMenu
  5851. ==========================================================================
  5852.       242: FECHO, FPRETTY, FMENU error: too many lines between labels
  5853.             These commands can only read in 25 lines (which is all you'd
  5854.       normally want!) and will give an error if the end of the file or
  5855.       another label is not reached before 26 lines (exclusive of
  5856.       comments) are read.
  5857. ==========================================================================
  5858.       243: FECHO, FPRETTY, FMENU error: no lines between labels
  5859.             Either the first line in a file where no label was given or
  5860.       the line following the label give was itself a label line (i.e.
  5861.       began with :)
  5862. ==========================================================================
  5863.       245: Too many items in MENU or FMENU
  5864.             Menus are limited to 16 choices.
  5865. ==========================================================================
  5866.       246: Improper FMENU lines
  5867.             The first line in FMENU began with an @ which is only used to
  5868.       separate menu items from help text
  5869. ==========================================================================
  5870.       250: HALTIF error: No comparison given
  5871.              Each HAltif parameter must have an =, > or < (NOTE: THE > OR
  5872.       < MUST BE ENTERED AS $g OR $l TO AVOID A DOS REDIRECTION)
  5873. ==========================================================================
  5874.       253: Turbo Pascal Runtime Error!
  5875.             Most errors indicate mistakes you made or system errors but
  5876.       if you get this message, it means that we made an error because we
  5877.       failed to catch an error and the underlying Turbo Pascal code was
  5878.  
  5879.  
  5880.     Chapter VIII:ERROR MESSAGES                               Page 109
  5881.  
  5882.  
  5883.  
  5884.  
  5885.                   Documentation for BATUTIL, Version 1.0 
  5886.  
  5887.  
  5888.       called into play.  Please report the problem to us with the extra
  5889.       information displayed on the screen
  5890. ===========================================================================
  5891.  
  5892.  
  5893.  
  5894.  
  5895.  
  5896.  
  5897.  
  5898.  
  5899.  
  5900.  
  5901.  
  5902.  
  5903.  
  5904.  
  5905.  
  5906.  
  5907.  
  5908.  
  5909.  
  5910.  
  5911.  
  5912.  
  5913.  
  5914.  
  5915.  
  5916.  
  5917.  
  5918.  
  5919.  
  5920.  
  5921.  
  5922.  
  5923.  
  5924.  
  5925.  
  5926.  
  5927.  
  5928.  
  5929.  
  5930.  
  5931.  
  5932.  
  5933.  
  5934.     Chapter VIII:ERROR MESSAGES                               Page 110
  5935.  
  5936.  
  5937.  
  5938.    INDEX
  5939.  
  5940.    #Altmon          23,75                 ECho             34,89
  5941.    #Comm            24,75                 EDitenv          66,89
  5942.    #Disk            21,75                 environment      12,55
  5943.    #Env             21,75                 environment,loading 63
  5944.    #Floppy          24,76                 environment, saving 62
  5945.    #Game            24,76                 ENvrep           57,90
  5946.    #Intel           23,76                 EOline           35,90
  5947.    #Keyboard        23,76                 ERrorlevel    11,29,90
  5948.    #Lim             20,76                 EXist            25,90
  5949.    #Mem             20,77                 Fatal Errors       104
  5950.    #Prn             24,77                 FDir             25,91
  5951.    #Rodent          23,77                 FEcho            13,91
  5952.    #Terminal        22,77                 file pick list      61
  5953.    #Vmode           22,77                 filename parsing    32
  5954.    #Whichmon        22,78                 FKey             45,91
  5955.    #Xtended         21,78                 FMenu         13,44,92
  5956.    $Translate       30,80                 FPretty          13,92
  5957.    4DOS          8,20,57                  GEtkey        47,49,92
  5958.    ?Length          59,80                 HAltif           15,93
  5959.    ?Size            59,81                 help                 8
  5960.    @Ansi            23,81                 HImem            20,93
  5961.    @Disk            21,81                 HOur             19,93
  5962.    @Env             21,81                 IS_A_DEVICE.        26
  5963.    @Floppy          24,82                 KIllenv          62,93
  5964.    @Lim             21,82                 label               14
  5965.    @Mem             20,82                 laptop               9
  5966.    @Prn             24,83                 LEngth           59,94
  5967.    @Terminal        22,83                 LIm              20,94
  5968.    @Xtended         21,83                 line editor         14
  5969.    ^Translate       30,84                 LOadenv          62,94
  5970.    ADdpath          64,84                 loading the
  5971.    AScii               52                      environment    63
  5972.    ASciiread           84                 Lock status         54
  5973.    ATtribute        35,85                 MAke                94
  5974.    BEcho            37,85                 MAkefile            29
  5975.    BIgchar             86                 MEnu          43,45,95
  5976.    BIGECHO             36                 MENUDEMO            44
  5977.    BPretty             86                 menus               67
  5978.    CArousel         20,86                 metastrings         30
  5979.    CHeck            26,87                 MHeader          45,95
  5980.    CLs              35,87                 minimal truncation  10
  5981.    COl           40,51,87                 MInute           19,95
  5982.    consultant's license 3                 MNattribute      35,95
  5983.    Control Break       16                 MOnth            19,96
  5984.    CSent            49,87                 NBeep            65,96
  5985.    cursor           13,40                 NFlush           49,96
  5986.    CUrsor              88                 NMouse           43,96
  5987.    DAte             19,88                 NSound           41,96
  5988.    DElpath          64,88                 NUmberfiles      27,97
  5989.    DOs              19,88                 OView            20,97
  5990.    DRive            20,89                 parsing             32
  5991.    DView            20,89                 path control        64
  5992.  
  5993.  
  5994.  
  5995.  
  5996.    PAthedit         65,97
  5997.    Pause mode       10,97
  5998.    PIANOMAN            41
  5999.    pick list           61
  6000.    PMatch           53,98
  6001.    POp              45,98
  6002.    PRetty           35,98
  6003.    PROMPT metastrings  30
  6004.    QLock            54,98
  6005.    QUery            59,99
  6006.    Quiet mode           9
  6007.    registration         3
  6008.    ROw                 40
  6009.    ROw              51,99
  6010.    RUn              27,99
  6011.    SAvenv          62,100
  6012.    saving the
  6013.          environment   62
  6014.    SCanread        52,100
  6015.    SEt             58,100
  6016.    SHadow          45,100
  6017.    SOund           41,101
  6018.    STACKEY metastrings 31
  6019.    standard output     41
  6020.    STdout          41,101
  6021.    syntax              10
  6022.    TOdayfile       28,101
  6023.    USername        52,102
  6024.    Verbose mode     9,102
  6025.    VIsual          49,102
  6026.    WARNING             56
  6027.    WEekday         19,103
  6028.    WHATEL              27
  6029.    Year            19,103
  6030.  
  6031.